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This  thesis  describes  the  design  and  software  for  a  computer  con¬ 
trolled  data  collection  system.  A  MCB  Z-80  development  system  with  an  AIO 
analog  input  board  was  both  the  target  hardware  for  the  data  collection  system 
and  the  computer  system  the  software  was  developed  on.  The  software  des¬ 
cribed  in  this  thesis  is  a  mixture  of  PL Z,  a  Pascal  like  language,  and  Z-80  assem¬ 
bly  language  with  hooks  from  both  into  the  development  system's  RIO  Operating 
System. 

The  software  doesn't  implement  the  full  design  and  isn't  com¬ 
pletely  bug  free.  The  difficulties  of  too  little  time  and  too  much  code  to  debug  took 
their  toll.  I  have  flagged  weak  points  and  logged  my  suspicions  where  appropri¬ 
ate  in  the  code  descriptions. 

Special  thanks  go  to  the  Apple  Computer  Company  for  their 
development  of  the  Macintosh,  LaserWriter,  and  MacWrite.  Without  these 
products  this  thesis  would  never  have  been  written. 
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s  /  A  computer  controlled  data  collection  system  was  designed  and 

partially  implemented  in  software.  The  design  concept  is  for  a  data  collection  unit 
to  be  placed  inside  the  system  being  tested  where  it  stores  the  test  data  in  an 
internal  memory.  Post-test  this  internal  unit  is  connected  to  and  polled  by  an 
external  control  and  data  storage  unit  which  archives  the  data.  Both  units  are 
computers.  This  combination  of  an  internal  data  collection  unit  and  an  external 
control  and  storage  unit  is  intended  for  testing  applications  where  it  is  either 
undesireable  or  not  possible  to  connect  the  sytem  being  tested  to  external  data 
recording  devices  during  the  test  event. 

The  partial  implementation  of  this  dual  unit  data  collection  system 
design  was  performed  on  a  Zilog  MCZ  Z-80  development  system  in  PLZ,  a 
Pascal-like  language,  and  Z-80  assembly  language.  Routines  to  improve  the 
input  /  output  and  hardware  access  of  PLZ  were  written  and  used.  The  software 
to  implement  the  internal  data  collection  unit  and  portions  of  the  external  control 
and  data  storage  unit  were  also  written.  The  internal  unit  routines  employ  a  Zilog 
Counter  Timer  Circuit  to  generate  sampling  period  interrupts.  The  analog  to 
digital  conversion  is  accomplished  via  a  Zilog  Analog  Input  Output  (AIOI)  board. 
The  data  collection  system  is  not  fully  operational,  j , 
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I.  Introduction 


Whenever  a  system  is  tested,  a  major  part  of  the  activity  is  collection  of 
performance  data.  "Did  it  work  ?"  is  not  a  question  answered  by  the  outcome  of 
test  alone.  Rather  it  is  answered  by  an  evaluation  based  on  the  information  col¬ 
lected  during  the  test.  In  the  past,  this  performance  data  might  have  been  man¬ 
ually  collected,  notes  carefully  recorded  in  an  lab  book,  or  as  a  photographic 
image  of  an  oscilloscope  trace.  Today's  technology  permits  the  collection  and 
storage  of  performance  data  in  electronic  forms,  both  analog  and  digital.  Besides 
automating  the  data  collection  process,  this  electronic  collection  of  data  permits 
analysis  without  having  to  manually  reenter  the  data  into  computers. 

The  automated  collection  of  performance  data  is  accomplished  by 
attaching  sensors  to  the  system  under  test  and  then  connecting  the  sensors  to 
some  data  recording  equipment.  The  sensors  translate  the  physical  responses  of 
the  system  being  tested  into  electrical-  signals.  Examples  of  sensors  include 
strain  gages  for  movement  and  pressure;  current,  electric  field  and  magnetic  field 
sensors  for  Electromagnetic  Pulse  testing,  and  microphones  for  human  speech. 
The  data  collection  equipment  stores  the  sensor  generated  signals.  Examples  of 
recording  equipment  include  tape  recorders  and  transient  digitizers  like  Tektronix 
7912s.  The  connection  between  the  sensor  and  the  data  recording  equipment 
can  range  from  simple  twisted  pair  wiring  to  multiplexed  fiber  optic  links  to  the  RF 
data  links  from  tagged  grizzly  bears  through  the  TDRSS  satellite  to  NASA's 
ground  stations.  The  length  and  type  of  connection  used  is  dependent  upon  the 
nature  of  the  system  being  tested. 

There  are  instances  in  testing  however  where  it  is  either  physically 
impossible  or  undesirable  to  connect  the  item  under  test  with  some  external  data 
recording  system.  For  example,  the  "black  boxes"  of  airplanes,  the  cockpit  voice 
recorders  and  the  flight  data  recorders,  are  internal  to  the  system.  It  is  not  feas¬ 
ible  to  hard  wire  aircraft  to  ground  based  recorders  or  squander  the  RF  spectrum 
on  data  links.  Another  example  is  Electromagnetic  Pulse  (EMP)  testing.  Exter¬ 
nal  data  recorders  can  not  be  wired  to  sensors  in  the  aircraft  undergoing  EMP 
testing  for  the  presence  of  these  conductors  alters  the  EMP  response  of  the  air¬ 
craft.  Use  of  dielectric  instrumentation  cables,  like  fiber  optics  is  one  solution, 
though  this  tethers  the  test  object.  RF  links  are  also  possible  though  complex  to 
set  up  and  often  limited  in  bandwidth.  Another  solution  exists  and  is  used.  The 
sensor  data  is  stored  within  the  system  being  tested  and  then  extracted  after  the 
test  event  is  over.  In  the  first  example,  the  flight  recorders  are  recovered  from  the 
crashed  aircraft;  the  crash  being  the  test  event.  In  the  EMP  example,  an  early 
procedure  was  to  put  oscilloscopes  with  cameras  inside  shield  boxes  (EMP  & 
noise  "proof"  enclosures)  and  place  these  boxes  within  the  aircraft;  the  exposed 
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film  was  recovered  after  each  EMP  exposure  (Ref  12).  In  both  cases,  the  data  is 
saved  in  recording  equipment  placed  inside  the  system  being  tested  and  then  the 
data  is  retrieved  after  the  test  is  over. 

This  thesis  investigation  considers  another  version  of  the  internal  data 
storage  approach  discussed  above.  The  sensors  on  the  item  under  test  are  con¬ 
nected  to  a  data  recording  unit  located  inside  the  test  item  as  shown  in  Figure  1 
below.  This  internal  data  collection  unit  is  a  microprocessor  /  memory  system  that 
samples  sensor  data  at  a  programmable  rates  and  saves  the  data  in  random 
access  memory  (RAM).  Pretest,  the  internal  data  collection  unit  is  programmed 
for  the  desired  sampling  by  the  external  control  and  data  storage  unit.  Next,  dur¬ 
ing  the  test,  the  links  between  the  internal  unit  and  the  external  unit  are  severed 
or  ignored.  Post-test,  the  internal  data  collection  unit  is  reconnected  to  the 
external  control  and  data  storage  unit.  The  data  is  then  transferred  out  of  RAM  to 
the  external  unit  and  saved  in  some  long  term  storage  medium  like  a  floppy  disk 
or  data  tape.  The  external  control  and  data  storage  unit  would  also  handle 
simple  data  scaling  and  printing  of  the  data  and  could  be  available  for  User  data 
manipulations  as  well. 


Figure  1 .  Data  Collection  System 


Both  the  internal  data  collection  unit  and  the  external  data  storage 
system  are  digital  devices  ,  adapted  through  their  software  for  the  specific  needs 
of  each  data  collection  effort.  The  object  code  of  the  collection  unit,  would  likely 
be  ROM  based;  for  the  storage  system  the  object  code  would  probably  be  called 
from  disk.  The  key  is  that  the  collection  unit  and  the  storage  system  must  com¬ 
municate  with  each  other  based  on  a  common  understanding  of  purpose.  An 
example  of  this  type  of  system  is  the  Tektronix  7912  and  a  post  test  polling  com¬ 
puter  (Ref  11).  This  thesis  deals  with  the  software  required  to  make  such  a  sys- 
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tern  work  (in  conjunction  with  the  hardware  of  the  system),  the  software  of  the 
internal  data  collection  unit  and  the  external  data  storage  system. 


Requirements  of  Data  Collection  System 

While  it  is  simple  to  state  the  purpose  of  a  data  collection  system,  "To 
Collect  Data",  it  is  more  important  to  examine  the  characteristics  or  attributes  re¬ 
quired  of  the  system.  The  primary  attributes  of  concern  for  this  data  collection 
system  are  accuracy,  data  integrity,  flexibility,  and  a  simple  user  interface.  In 
practice,  it  is  vital  to  quantify  the  specific  requirements  for  each  attribute;  to  define 
exactly  what  the  necessary  performance  characteristics  are.  As  this  thesis  is  not 
tageted  to  any  specific  application,  the  following  discussions  of  accuracy,  data 
integrity,  flexibility,  and  a  simple  user  interface  are  general. 


Accuracy 


For  a  data  collection  system  to  have  any  value,  the 
data  it  collects  must  as  accurately  as  possible  represent  the  original  physical 
phenomena  or  sensor  signals  that  were  sampled.  There  are  three  facets  to  this 
requirement  for  accuracy:  amplitude  fidelity,  sampling  period,  and  data  scaling. 
The  need  for  amplitude  fidelity  will  be  discussed  first. 

The  mapping  between  the  amplitude  of  the  analog  signal  being  sam¬ 
pled  to  the  digital  values  stored  has  several  variables:  analog  to  digital  (A/D)  con¬ 
version  fidelity,  linearity,  and  sensor  impacts.  First,  the  analog  to  digital  (A/D) 
conversion  must  have  as  much  fidelity  as  possible.  Obviously  more  bits  do  yield 
greater  fidelity.  This  increased  fidelity  is  paid  for  in  increased  hardware  costs  or 
settling  times.  The  objective  in  selecting  the  number  of  bits  of  the  A/D  converter  is 
to  match  its  conversion  range  to  the  data  signals  of  interest.  This  matching  has 
two  aspects,  maximum  amplitude  (or  dynamic  range)  of  the  input  signal  and 
resolution  (units  per  least  significant  bit  or  scaling)  required  by  the  test  applica¬ 
tion.  Any  A/D  converter  can  be  matched  to  the  maximum  expected  amplitude  of 
any  given  signal  through  the  use  of  attenuators  or  amplifiers;  the  resolution  of 
amplitude  is  another  matter  however.  Figure  2,  below,  shows  the  resolution 
variation  for  a  variety  of  A/D  converter  sizes  and  signal  dynamic  ranges.  The 
selection  of  the  size  of  the  converter  must  be  based  on  the  expected  dynamic 
range  of  the  signal  and  the  resolution  or  scaling  required.  If  there  is  a  mismatch 
in  dynamic  range  ,  the  analog  signal  may  overflow  the  A/D  converter  or  the  sig¬ 
nal  may  register  only  in  the  least  significant  digits.  Through  correct  matching  of 
the  input  signal  to  a  properly  sized  A/D  converter  with  amplifiers  or  attenuators, 
the  amplitude  of  the  analog  signal  will  be  accurately  represented  with  the  resolu¬ 
tion  necessary  for  the  specific  signal  or  sensor  of  interest. 
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Resolution  of  Least  Significant  Bit 


Total  Elements 

Size  o 
4-Bit 

Analog  tc 
8-Bit 

Digital  C< 
12-Bit 

Dnverter 

16-Bit 

Signal  Range^^ 

16 

256 

4,096 

65,536 

0  to  1 

.063 

.004 

.0002 

.00002 

0  to  10 

.625 

.039 

.0024 

.00015 

0  to  100 

6.25 

.391 

.0244 

.00153 

0  to  1 ,000 

62.5 

3.91 

.2442 

.01526 

Figure  2.  Resolution  of  Least  Significant  Bit  for  Various  Sized  Analog  to 
Digital  Converters  and  Input  Signal  Ranges 


A  second  variable  of  the  mapping  between  the  analog  signal’s  am¬ 
plitude  and  the  digital  values  is  linearity.  It  is  desirable  for  the  bit  change  to  be 
the  same  for  a  signal  amplitude  change  regardless  of  where  in  the  dynamic 
range  the  signal  change  occurs.  The  delta  bits  for  a  98.7  to  99.0  volt  change 
should  be  the  same  as  for  a  7.3  to  7.0  volt  change.  This  linearity  is  a  function  of 
the  A/D  converter  and  any  signal  conditioning  equipment  (attenuators  or  ampli¬ 
fiers).  Two  courses  of  action  are  available,  get  as  linear  a  system  as  possible  or 
measure  the  nonlinearity  and  extract  its  effects  posts  test. 

The  third  variable  is  the  sensor  itself.  Though  sensor  concerns  are 
outside  the  scope  of  this  thesis,  the  resolution  of  the  sensor  must  be  matched  to 
the  physical  phenomena  being  measured.  As  with  the  A/D  converter,  dynamic 
range  and  resolution  are  of  concern.  Linearity  is  a  concern  for  the  sensor  also. 


The  second  facet  of  the  requirement  for  accuracy  centers  on  the  sam¬ 
pling  period.  Of  foremost  concern  is  that  the  sampling  rate  be  sufficient  to  cap¬ 
ture  the  frequencies  of  interest  in  the  input  analog  signal.  Beyond  the  sampling 
rate,  are  two  aspects  of  concern  for  the  generation  of  the  sampling  period.  First, 
the  sampling  period  employed  must  be  stable;  that  is  the  time  between  samples 
is  constant  from  the  beginning  of  data  collection  through  the  end.  This  is  depen- 
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dent  upon  the  clock  used  to  trigger  individual  samples.  The  second  aspect  of 
concern  is  that  the  sampling  period  employed  should  be  what  was  specified. 
Few  things  could  distort  test  findings  more  than  to  have  the  time  base  unknow¬ 
ingly  off.  Correct  implementation  of  the  specified  sampling  period  is  a  function  of 
both  the  clock  used  and  the  routine  that  translates  the  specified  sampling  period 
into  hardware  controls  or  programming. 

The  preceding  paragraph  discusses  continuous  samplers.  Another 
type  of  sampler,  event  driven,  also  exist.  Event  driven  samplers  collect  data  only 
when  something  of  interest  occurs.  For  this  type  of  sampler,  timing  accuracy 
centers  on  knowing  when  the  event  occurred.  Event  driven  samplers  are  not 
within  the  scope  of  this  thesis  effort.  However,  for  continuous  samplers,  know¬ 
ledge  of  when  the  sampling  began,  or  a  time  tie  between  the  sampling  interval 
and  some  external  event  is  valuable. 


The  third  facet  of  accuracy  requirements  is  data  scaling.  Each  step 
from  the  actual  physical  phenomena  to  the  digital  data  stored  alters  the  represen¬ 
tation  of  the  phenomena.  A  pressure  of  3  KPa  is  translated  by  a  sensor  into  a  3 
volt  signal;  an  amplifier  boosts  this  to  27.3  volts;  a  12  bit  A/D  converter  transforms 
it  into  the  binary  string  1 0001 01111 00.  Data  scaling  is  the  process  of  convert¬ 
ing  this  binary  string  back  into  physical  parameters.  The  process  can  be  as 
straight  forward  as  multiplying  the  digital  value  by  a  single  scale  factor.  It  could 
be  a  complicated  filtering  effort  involving  multiplication  by  an  amplitude  depen¬ 
dent  scale  factor  to  remove  nonlinearities  produced  by  the  sensor.  In  either 
case,  the  scaling  process  must  be  uniquely  accomplished  for  each  sensor  to 
satisfy  this  third  facet  of  accuracy. 


Data  Integrity 


Data  integrity  is  the  second  attribute  required  of  a 
data  collection  system.  Data  integrity  simply  refers  to  the  data  being  protected 
from  loss  or  alteration  from  improper  or  inadvertant  actions.  Tests  are  not  inex¬ 
pensive  and  to  loose  test  data  or  have  it  altered  could  force  a  retest  or  perhaps 
acceptance  of  the  loss  of  unreproducable  data  (aircraft  flight  data  recorders  for 
example).  Also  including  in  data  integrity  is  data  traceability.  As  files  of  data  are 
manipulated,  it  is  vital  to  know  what  the  original  raw  data  file  was  and  which  file 
was  the  immediate  parent  of  the  manipulated  file. 
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A  data  collection  system  having  the  attribute  of  flex¬ 
ibility  is  a  system  that  can  readily  adapt  to  changing  data  collection  efforts.  This 
attribute  can  be  examined  from  two  perspectives,  the  flexibility  to  adapt  to  differ¬ 
ent  systems  being  tested  and  the  flexibility  to  adapt  to  changing  needs  during  the 
test  of  a  single  system. 

It  makes  sense  for  a  piece  of  test  equipment ,  such  as  a  data  collection 
system,  not  to  be  tailored  to  a  single  specific  system  under  test.  If  it  were  tailored 
it  would  have  to  be  developed  anew  for  each  new  system  being  tested.  Instead, 
the  data  collection  system  should  be  sufficiently  broad  in  its  capabilities  to  sup¬ 
port  a  reasonably  wide  range  of  applications.  This  could  mean  being  able  to 
withstand  both  the  g-forces  of  an  aircraft  and  the  thermal  environment  of  a  tank  in 
desert  testing.  This  could  mean  being  able  to  record  information  from  both  a  cur¬ 
rent  transformer  hooked  to  a  high  voltage  line  and  a  strain  gage  on  a  tactical 
shelter  during  an  overpressure  test.  This  could  mean  being  able  to  both  record 
1,000  samples  in  10  seconds  of  transient  response  measurement  or  one  sam¬ 
ple  every  10  seconds  of  long  term  stability  measurements.  In  the  actual  devel¬ 
opment  of  a  data  collection  system,  the  scope  of  application  would  have  to  be 
clearly  defined  in  order  to  establish  firm  design  requirements.  The  following  are 
examples  of  the  kinds  of  variations  a  general  purpose  data  collection  system 
(intended  to  be  located  inside  the  object  under  test)  would  have  to  accomodate. 

Varied  Test  Environments.  The  data  collection  system,  particularly  the  internal 
unit,  should  be  able  to  operate  in  many  environment  such  as 
high  and  low  temperature,  electrical  noise,  RF,  salt  water  at¬ 
mosphere,  pressure,  dynamic  loads,  high  humidity  or  wet 
environments,  and  shock  or  vibration.  Producing  hardware 
that  can  function  in  these  environments  is  mostly  a  constru¬ 
ction  and  packaging  problem. 

Assorted  Sensors.  A  unit  intended  for  multiple  purposes  must  be  able  to  inter¬ 
face  with  many  different  kinds  of  sensors.  The  inputs  may  be 
differential  or  single  sided.  The  sensor  output  voltages  may  be 
in  a  millivolts  range  or  10's  of  volts.  The  impedances  of  the 
sensor  and  the  collection  unit  must  be  matched. 

Range  of  Sampling  Periods.  Sampiing  periods  range  from  well  above  106  sam¬ 
ples  per  second  for  nuclear  weapon  effects  (Ref  11)  to  less 
than  one  sample  per  hour  for  thermal  drift.  The  higher  sam¬ 
pling  rates  will  force  the  use  of  faster  analog  to  digital  conver¬ 
ters,  processors,  and  memory. 
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Number  of  Samples.  The  number  of  samples  needed  will  vary  greatly  based  on 
two  factors,  the  sampling  period  needed  and  the  frequency 
with  which  the  stored  data  can  be  extracted.  A  system  requir¬ 
ing  only  one  sample  per  hour  could  go  nearly  a  whole  year  on 
8K  bytes  of  memory.  On  the  other  hand,  at  106  samples  per 
second,  64K  of  memory  would  be  filled  in  less  than  100  milli¬ 
seconds.  The  need  for  large  numbers  of  samples  will  rapidly 
complicate  the  internal  data  collection  unit.  More  memory 
means  greater  power  consumption,  more  complicated  ad¬ 
dressing,  and  larger  physical  size.  The  longer  the  interval 
between  extraction  of  stored  data,  the  larger  the  memory 
needs  to  be. 

Frequency  of  Access.  This  refers  electrical  access  for  retrieval  of  data  or  charg¬ 
ing  of  batteries.  If  the  access  is  infrequent,  then  the  power  sup¬ 
ply  will  have  to  sufficiently  large  to  power  the  unit  between  ac¬ 
cesses.  The  frequency  of  access  also  impacts  the  size  of  the 
data  storage  memory  as  discussed  above. 

Physical  Dimensions.  As  the  data  collection  unit  will  be  located  within  test 
objects,  It  should  be  as  small  as  possible  and  be  readily 
mountable. 


In  the  actual  design  and  implementation  of  an  internal  data  collection 
unit,  trade-offs  would  have  to  be  made  between  the  above  capabilities  and  other 
parameters  such  as  cost.  For  example,  one  test  environment,  nuclear  radiation 
testing,  imposes  significant  problems  for  electronics.  To  include  this  environment 
upon  a  general  purpose  data  collector  would  impose  severe  penalties  on  other 
applications.  Extremely  long  sampling  periods  or  very  large  numbers  of  samples 
are  other  examples  of  needs  outside  the  bounds  of  a  "general  purpose"  data  col¬ 
lection  system.  For  these  kinds  of  requirements,  specialized  units  would  proba¬ 
bly  be  created;  these  special  needs  just  push  hardware  flexibility  too  far.  The 
software  however,  would  be  consistent. 


The  second  perspective  on  the  required  attribute  of  flexibility  is  the 
ability  of  the  data  collection  system  to  adapt  to  changing  needs  during  the  test  of 
a  single  system.  Perhaps  predictions  were  off  and  signals  that  were  expected  to 
be  10’s  of  volts  are  actually  just  a  few  volts.  To  have  the  capability  to  remotely 
adjust  the  internally  mounted  data  collection  unit  is  quite  desirable.  With  remote 
adjustment  or  programming  the  test  apparatus  wouldn't  have  to  be  torn  apart  to 
make  adjustments.  Perhaps  the  item  under  test  itself  is  inaccessible  except  via 
control  lines.  It  is  desirable  to  have  the  capability  to  change  the  following  items 
remotely. 
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Input  Channel/Sensor  Selection.  With  the  ability  to  remotely  shift  between  chan¬ 
nels  or  sensor,  a  single  internal  collection  unit  could  perform  the 
function  of  several.  This  is  an  advantage  only  for  reproducible 
tests. 

Attenuator  /  Amplifier  Selection.  The  ability  to  change  the  gain  remotely  is  vital. 

The  example  above  of  errored  predictions  shows  an  application 
where  remote  adjustment  of  attenuators  would  be  useful. 

Sampling  Rate.  As  a  unit  is  switched  between  sensors  or  to  accommodate  dif¬ 
ferent  test  interests,  the  sampling  period  of  the  unit  needs  to  be 
changed.  For  example,  one  test  run  might  be  made  at  1 K  samples 
per  second  to  measure  the  initial  transient  response  followed  by  a 
second  test  with  10  samples  per  second  to  examine  the  long  term 
response. 

Number  of  Samples.  Given  the  variation  in  sensors  and  sampling  rates,  the  num¬ 
ber  of  samples  collected  needs  to  be  remotely  controlled. 

Mode  of  Operation.  Should  the  test  go  into  a  hold,  it  would  be  useful  to  place  the 
internal  data  collection  units  into  some  standby  state  to  conserve 
battery  charge.  Other  states  of  interest  would  be  battery  charge, 
programming,  off,  and  ready,  self-test/readiness  check. 


Flexibility  is  thus  a  two  perspective  attribute  of  the  requirements  for  the 
data  collection  system.  The  ability  to  adapt  to  both  varied  test  requirements  and 
changes  in  an  ongoing  test  are  needed. 


Simple  User  Interface 


The  final  requirements  attribute  of  the  data  collec¬ 
tion  system  is  that  it  have  a  user  interface.  This  involves  four  factors,  clear 
instructions,  error  diagnostics,  operation  on  the  users'  terms,  and  fool  tolerance. 
The  first  two  factors  revolve  around  the  messages  passed  to  the  user.  Instruc¬ 
tions  must  clearly  spell  out  what  the  user  is  to  do  and  the  format  it  should  be  done 
in.  Error  messages  must  tell  what  went  wrong,  where  it  went  wrong,  and,  if  possi¬ 
ble,  why  it  went  wrong. 

Operation  on  the  users'  terms  refers  to  two  efforts.  First,  all  commands 
need  to  be  in  "real  world"  terms,  not  values  selected  for  ease  of  programming. 
For  example  sampling  periods  should  be  specified  in  seconds,  not  clock  cycles. 
By  requesting  and  expressing  information  in  terms  readily  understood  by  the 
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users,  the  ease  of  use  of  the  system  is  greatly  enhanced.  The  second  portion  of 
operation  on  the  users’  terms  is  for  the  computer  to  do  the  work.  If  translations 
between  units  are  required,  the  routine  should  perform  the  translation  rather  than 
forcing  the  users  to  do  so.  Also  included  is  telling  the  users  what  is  happening. 
Nothing  disturbs  a  person  more  than  sitting  by  a  computer  which  hasn’t  "said"  a 
thing  for  several  minutes.  Status  feed  back  is  important. 

The  final  factor  of  a  simple  user  interface  is  fool  tolerance.  While  no 
system  can  be  made  totally  fool  proof,  reasonable  steps  can  be  taken  to  avoid 
problems.  The  factors  already  discussed  go  a  long  way  towards  fool  tolerance; 
the  remaining  step  is  error  checking  on  the  user  input.  Are  the  users'  input  com¬ 
mands  in  range,  consistant,  of  the  proper  format,  and  complete?  If  not  tell  the 
users  what  is  wrong  and  remind  them  of  the  allowable  inputs.  These  steps  will 
not  fool  proof  the  system  (the  reset  switch  will  still  get  bumped)  but  they  will 
greatly  reduce  the  occurrence  of  inadvertant  errors. 


In  summary,  the  data  collection  system  must  be  accurate,  must 
ensure  data  integrity,  must  have  sufficient  flexibility,  and  must  present  a  simple 
interface  to  the  users  of  the  system.  Though  there  are  design  trade-offs  within 
and  among  these  requirements,  a  reasonable  general  purpose  data  collection 
system  design  can  be  derived  from  them. 


Hardware  Used  for  this  Thesis  Effort 

Were  this  thesis  effort  an  actual  development  of  a  data  collection  sys¬ 
tem,  a  substantial  portion  of  the  effort  would  center  on  the  selection  or  design  of 
the  hardware  which  implements  the  collection  system.  For  this  thesis  effort,  the 
hardware  was  a  given.  The  thesis  effort  focused  on  the  design  and  implemen¬ 
tation  of  the  software  needed  to  make  the  data  collection  system  functional. 

The  hardware  used  for  this  thesis  effort  was  a  Zilog  MCZ-80  develop¬ 
ment  system.  It  was  used  for  several  reasons.  It  was  available,  it  had  an  analog 
to  digital  (A/D)  converter  board,  timing  chips  for  generating  sampling  intervals 
were  present,  a  high  level  language  similar  to  Pascal  was  available,  and  exten¬ 
sive  assembly  language  programming  tools  were  available.  Thus  the  MCZ  sys¬ 
tem  met  many  of  the  requirements  for  the  data  collection  system  discussed  in  the 
previous  section  and  provided  the  software  development  tools  needed  to  carry 
out  the  thesis  effort.  The  following  is  an  overview  of  the  MCZ  system  used  as 
both  the  software  development  system  and  as  the  target  hardware  for  the  data 
collection  system  (Refs  1  through  9). 
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The  MCZ  development  system  consisted  of 

1 .  Equipment  chassis  with  power  supply  and  card  cage 

2.  Two  8  inch  floppy  disk  drives. 

3.  A  Zilog  MCB  Microcomputer  board.  This  board  held: 

Z-80  microprocessor 
3K  ROM  with  monitor  routine 
System  Clock 
16K  of  RAM 

Z-80  CTC  {Counter  Timer  Circuit) 

Z-80  PIO  (Parallet  Input  Output) 

USART  {Universal  Synchronous  Asynchronous  Receiver 
Transmitter) 

4.  A  Zilog  MCD  Board  (memory  &  disk  controller)  48K  RAM 

5.  A  Zilog  SIB  Board  (serial  interface  board,  has  three  CTCs) 

6.  A  Zilog  AIO  Board  (analog  input  output  card)  which  has  a  12  bit 

analog  to  digital  converters. 

7.  RIO  Operating  System  which  includes  disk  operating  system. 

8.  An  ADAM-3  terminal. 

9.  A  NEC  Spinwriter  Printer. 

To  prepare  the  MCZ  system  for  this  thesis  effort,  the  AIO  board  had  to 
be  integrated  into  the  system  (Ref  8:Sec  2,  Sec  3:5);  it  had  never  been  installed. 
Installing  the  AIO  board  required  minor  rewiring  of  the  motherboard  of  the  card 
cage,  addition  of  backplane  connecters  for  the  AIO  board's  interfaces,  and  the 
fabrication  of  connection  board  to  permit  easy  hookup  to  the  AIO  board's  inter¬ 
faces.  Once  the  AIO  board  was  installed,  its  disk  based  diagnostics  were  run  and 
the  board's  alignment  was  checked  and  adjusted  as  required  (Ref  8:  Sec  5). 


As  target  hardware  for  the  data  colection  system,  the  MCZ  hardware 
met  several  of  the  data  system  requirements  discussed  in  the  previous  section. 
The  system  possessed  accuracy  with  both  a  12  bit  analog  to  digital  converter  and 
ample  hardware  for  generating  accurate  sampling  periods  (Ref  2,  7,  and  8).  The 
RIO  operating  system  supported  disk  file  operations  permitting  protection  of  data 
integrity  (Ref  4).  The  system  was  relative  flexible  having  sixteen  input  channels 
for  the  analog  to  digital  converter  (Ref  8:1)  and  sufficient  memory  for  both  the  pro¬ 
grams  and  data  sample  storage.  The  Adam-3  terminal  would  serve  as  the  user 
interface;  the  bulk  of  the  simple  user  interface  up  to  the  software. 

While  the  MCZ  system  met  many  of  the  requirements  for  the  data  col¬ 
lection  system,  it  did  not  mesh  well  with  the  hardware  concept  of  the  data  collec¬ 
tion  system.  The  MCZ  system  is  a  single  system;  the  data  collection  system  con¬ 
cept  calls  for  two  distinct  hardware  units,  the  internal  data  collection  /  temporary 
storage  unit  and  the  external  control  /  archival  storage  unit.  This  mismatch  be- 
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tween  the  realities  of  the  MCZ  hardware  and  the  hardware  concept  of  the  data 
collection  system  is  largely  resolved  in  software. 


The  focus  of  this  thesis  effort  is  the  software  required  to  make  the  data 
collection  system  work.  Thus  the  reality  that  a  single  set  of  hardware  was  being 
used  could  be  masked,  in  part,  by  making  the  software  of  the  two  data  collection 
units  separate  and  distinct.  As  will  be  shown,  the  software  developed  for  this 
thesis  effort  maintains  this  division.  The  software  of  the  internal  unit  does  not  talk 
directly  to  the  user  except  for  a  trigger  signal.  The  software  of  the  external  unit 
does  not  have  direct  access  to  the  analog  to  digital  conversion.  The  program¬ 
ming  the  external  unit  provides  to  the  internal  unit  is  represented  by  the  para¬ 
meters  passed  between  the  software  of  the  external  unit  and  the  software  of  the 
internal  unit.  Thus,  while  a  single  set  of  hardware  is  used,  the  software  of  the 
data  collection  system  is  separated  into  internal  and  external  units. 


Overview  of  System  Design 

In  designing  the  software  of  the  data  collection  system  software,  the 
first  question  was  "What  tasks  will  the  user  need  to  accomplish  V  The  principal 
task  is  to  collect  the  data,  but  what  else  would  the  user  need  to  do.  Three  specific 
tasks  and  one  general  activity  area  were  fidentified.  The  data  read  in  from  the 
internal  unit  and  stored  in  the  external  unit  is  raw  data.  It  is  in  the  digital  form 
received  from  the  A/D  converter.  Thus,  an  important  task  is  to  translate  this  raw 
data  into  data  set  in  real  world  terms;  the  raw  data  needs  to  be  scaled.  To  main¬ 
tain  data  integrity,  this  scaled  data  should  be  written  into  a  new  file  leaving  the 
original  raw  data  file  unchanged.  To  accomplish  the  scaling,  the  user  must 
specify  the  scale  factor  to  be  used;  a  unique  scale  factor  for  each  input  channel. 
Thus  a  third  type  of  file  is  needed,  a  file  of  scale  factors.  Having  translated  the 
information  of  the  raw  data  file  into  the  information  of  the  scaled  data  file,  the 
users  would  probably  want  to  print  out  the  data  or  perform  further  manipulations 
of  their  design  or  choice.  The  printing  out  of  data  is  the  third  specific  task  of  the 
data  collection  system  and  the  user  defined  manipulations  are  the  general 
activity  area.  One  final  feature  of  the  data  collection  system  is  a  common  user 
interface  so  all  the  the  tasks  can  be  invoked  in  a  consistent  fashion.  Thus  the  five 
tasks  the  data  collection  system  must  accomplish  are 

Collection  and  Storage  of  Data 
Setup  of  Scale  Factors  in  a  File 

Produce  a  File  of  Scaled  Data  from  the  Raw  Data  and  Scale  Factors 
Output  of  Data  Files  (Both  Raw  and  Scaled) 

Support  User  Manipulations  of  Data 
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all  with  a  consistent  user  interface. 

Figure  3A  below  shows  how  these  five  tasks  or  processes  interact  with 
each  oth^r,  the  operating  system,  and  the  user.  The  common  user  interface  is 
present  as  an  interface  or  interpreter  between  the  operating  system  and  the  pro¬ 
cesses  of  the  data  collection  system.  Though  the  figure  implies  that  all  operating 
system  calls  would  go  through  the  user  interface,  this  is  not  necessarly  the  case. 
Once  a  process  begins  its  execution,  standard  operating  system  calls  and  mes¬ 
sages  to  the  user  would  go  directly  to  the  operating  system  rather  than  through 
the  interface.  Thus  elements  of  the  common  user  interface  are  implemented 
through  out  the  processes  of  the  data  collection  system. 


Figure  3B  shows  the  elements  used  to  implement  the  data  collection 
system  shown  in  Figure  3A  and  shows  the  hierarchy  of  these  elements.  The  pro¬ 
cess  of  Collect  and  Store  Data  of  Figure  3A  is  implemented  by  Collect_Data 
Module  and  Sampler  Module  along  with  the  hardware  elements  and  calls  to  the 
operating  system.  The  Set  Up  Scale  Factor  Filed  process  is  implemented  by  the 
Scale_Factor  Module  of  Figure  3B,  again  assisted  by  operating  system  calls. 
The  Figure  3A  processes  of  Scale  Data,  Output  Data,  and  User  Data  Manipula¬ 
tions,  were  not  implemented.  Shown  in  Figure  3B  as  portions  of  the  operating 
system  are  three  modules  of  general  support  software  which  were  implemented 
as  software  development  aids.  The  common  user  interface  of  Figure  3A  is  par¬ 
tially  implemented  and  is  represented  in  Figure  3B  by  some  of  the  calls  to  the 
operating  system  from  Collect_Data  Module  and  Scale_Factor  Module. 


In  the  following  paragraphs,  the  activities  performed  by  each  process 
of  the  data  collection  system  and,  when  appropriate,  an  overview  of  how  the  pro¬ 
cess  was  implemented  the  will  be  presented.  The  purpose  and  design  of  the 
general  support  software  will  also  be  presented.  Information  of  greater  detail  on 
design  and  implementation  for  each  module  is  presented  in  later  sections  of  this 
thesis  for  each  software  module.  Please  note  that  the  software  developed  for  this 
thesis  effort  addresses  only  the  Data  Collection  and  Storage  process  and  the  Set 
Up  Scale  Factor  File  process.  These  processes  were  implemented  since  their 
output  is  required  as  input  to  the  remaining  processes.  Also,  the  remaining 
processes  are  simpler  to  implement  and  can  be,  in  part,  built  from  the  routines  of 
the  implemented  processes. 
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Figure  3B.  Hierarchical  Relationships  Between  Components  of  the  Data 
Collection  System  Components,  the  Operating  System,  and  the  User. 
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Early  in  the  design  process  one  of  the  questions 
raised  was  which  language  should  this  data  collection  system  be  implemented 
in,  PLZ,  Zilog's  Pascal  like  language,  or  Z-80  assembly  language.  PLZ  offered 
some  of  the  benefits  of  a  high  level  language  such  as  mathematical  operations. 
PLZ  however  was  quite  cumbersome  in  the  string  input  and  output  which  would 
be  required  for  the  user  interface.  Assembly  language  would  be  fast  and  offered 
direct  access  to  input  output  ports.memory,  and  the  Z-80  registers.  On  the  other 
hand,  Z-80  assembly  language  was  unfamiliar,  10  was  even  harder  than  PLZ, 
and  math  operations  would  be  far  more  difficult.  The  selected  approach  was  to 
use  the  best  qualities  of  both  PLZ  and  Z-80  assembly  language  plus  providing 
some  software  "improvements"  to  PLZ.  The  software  improvements  focused  on 
two  areas,  string  input  and  output,  and  on  access  to  system  hardware.  The  string 
input  and  output  improvements  became  the  Enhancements  Module;  the  hard¬ 
ware  access  routines  became  the  Utility  Module. 

The  PLZ  Language  routines  of  the  Enhancements  Module  were  writ¬ 
ten  to  make  string  input  and  output  easier  in  PLZ.  The  routines  were  written  to 
approximate  the  standard  Pascal  read  and  write  statements  (Ref  10:  Sec  7.2). 
The  major  difference  is  that  the  Enhancements  Module  routines  all  have  in  input 
parameter  for  the  logical  unit  number,  where  Pascal  handles  device  specification 
as  an  optional  parameter  with  the  compiler  sorting  things  out.  The  PLZ  compiler 
was  not  capable  of  this.  The  choice  for  the  Enhancements  Module  was  to  use  a 
mandatory  logical  unit  parameter  or  add  new  routines  and  global  variables  to 
switch  between  logical  units.  The  logical  unit  parameter  approach  was  selected 
as  it  is  closer  to  the  Pascal  implementation  and  would  yield  far  more  readable 
code.  The  Enhancements  Module  routines  were  fully  developed  and  tested. 

The  Utility  Module  assembly  language  routines  were  initially  written  to 
give  PLZ  language  programs  access  to  the  AIO  board.  This  purpose  was  expan¬ 
ded  to  give  PLZ  language  routines  access  to  other  portions  of  the  system  not  nor¬ 
mally  accessible  to  PLZ.  The  module  ultimately  contained  nine  assembly  lan¬ 
guage  routines.  They  provide  access  to  input/output  ports,  individual  memory  lo¬ 
cations,  the  system  date,  the  operating  system  memory  manager,  and  the  enabl¬ 
ing  /  disabling  of  the  Z-80  CPU  interrupts.  The  nine  assembly  language  routines 
of  the  Utility  Module  were  completely  developed  and  tested. 

With  the  "improvements"  provided  by  the  Enhancements  Module  and 
the  Utility  Module,  development  of  the  data  collection  system  software  could 
begin. 
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This  process  is  the  heart  of  the  data  collection  system 
for  it  is  in  this  process  that  the  analog  data  is  collected,  converted  to  digital  data, 
placed  in  temporary  storage,  transferred  to  the  external  data  storage  unit,  and 
archived  on  magnetic  media.  The  design  of  this  process  and  its  implementation 
in  software  focussed  on  two  competing  sets  of  constraints.  First,  the  design 
looked  the  requirements  for  the  data  collection  system  discussed  in  the  previous 
section.  Second,  the  design  had  to  live  within  the  constraints  of  the  Zilog  MCZ 
development  system.  In  addition,  the  software  of  the  internal  data  collection  / 
temporary  storage  unit  and  the  software  of  the  external  control  /  archival  storage 
unit  had  to  be  separate  and  distinct  to  keep  faith  with  the  hardware  concept  of  the 
data  collection  system.  The  design  process  for  the  Collect  and  Store  data  pro¬ 
cess  looked  at  three  basic  areas,  the  analog  to  digital  conversion,  the  timing  of 
the  sampling  periods,  and  the  archival  storage  of  the  converted  data. 


Analog  to  Digital  Conversion.  The  design  of  the  analog  to  digital 
conversion  portion  of  the  Collect  and  Store  Data  process  was  based  on  the  capa¬ 
bilities  of  the  AIO  (Analog  Input  Output  board).  This  board  satisfies  many  of  the 
requirements  outlined  in  the  opening  section.  The  board  has  a  12  bit  analog  to 
digital  (A/D)  converter;  this  meets  the  needs  for  accuracy.  Via  programming,  the 
board  can  address  any  one  of  sixteen  input  channels;  this  meets  the  flexibility 
need  for  in  place  adaptability.  The  A/D  converter  settles  in  about  20  micro¬ 
seconds  (Ref  8:  Sec  3.5.5).  Giving  a  liberal  allowance  for  program  overhead  this 
permits  a  minimum  sampling  period  of  about  50  microseconds,  a  reasonable 
minimum  for  a  general  purpose  data  collection  system.  The  board  is  hardwired 
for  +/-  10  volt  full  scale  inputs  and  coding  the  output  in  two’s  complement  format 
(Ref  8:  Sec  3.5.1). 

Given  the  capability  of  the  AIO  board,  the  method  of  employment  was 
determined.  The  AIO  board  would  be  programmed  into  a  polled  input  mode  (Ref 
8:  Sec  4).  Then,  upon  receipt  of  a  timing  signal,  the  desired  input  channel  num¬ 
ber  would  be  written  to  the  board;  this  initiates  an  A/D  conversion.  The  control¬ 
ling  program  then  goes  into  a  loop,  polling  the  AIO  board's  status  register  until 
the  data  ready  flag  is  raised.  The  controlling  routine  then  reads  the  data  from  the 
AIO  board  and  stores  it  in  memory.  This  sequence  is  repeated  for  each  timing 
pulse.  Initial  design  of  the  software  was  accomplished  in  PLZ.  This  initial  soft¬ 
ware  is  the  AIO.PLZ.S  Module.  For  the  final  program,  assembly  language  was 
selected  for  reduced  overhead  and  simpler  handling  of  the  timing  pulses.  The 
assembly  language  program  which,  among  other  things,  implements  this  process 
is  the  Sampler  Module,  the  software  of  the  internal  unit  of  the  data  colection 
system. 
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Timing  of  Sampling  Periods.  The  second  general  area  of  the 
Collect  and  Store  Data  process  is  the  selection  and  generation  of  the  sampling 
periods.  The  implementation  of  this  timing  is  based  on  the  timing  capabilities  of 
the  CTCs  (Counter  Timer  Circuit)  of  the  MCZ  Development  System's  SIB.  The 
CTC  can  be  easily  programmed  to  generate  periodic  interrupts  with  intervals  of 
6.515  microseconds  to  26.68  milliseconds  (Ref  7:  Sec  3.7).  This  timing  capability 
meets  the  needs  of  accuracy  and  begins  to  satisfy  the  requirement  for  flexibility 
discussed  in  the  opening  section.  The  26.68  millisecond  maximum  however  is 
not  sufficiently  long  for  a  general  purpose  data  collection  system.  So,  a  sixteen 
bit  counter  was  added.  The  combination  of  the  CTC  timer  and  a  sixteen  bit  coun¬ 
ter  yields  a  maximum  timing  period  of  29.14  minutes;  this  meets  the  needs  of 
flexibility. 

Building  upon  the  capabilities  of  the  CTC,  the  sample  period  timing 
software  of  the  Collect  and  Store  Data  process  was  designed.  The  software  had 
four  purposes,  calculating  the  CTC  programming  values,  initializing  the  CTC 
interrupts  for  the  sampling  periods,  determining  the  interrupt  service  routine  para¬ 
meters,  and  shut  down  of  the  CTC  interrupts.  Since  the  calculation  of  CTC  pro¬ 
gramming  values  is  a  math  intensive  effort,  this  task  is  accomplished  by  a  PLZ 
routine  in  the  Collect_Data  Module  (external  unit).  These  values  are  passed  to 
the  Sampler  Module  (internal  unit)  where  the  CTC  is  programmed.  Also  inside 
the  Sampler  Module  are  the  interrupt  service  routines.  The  interrupt  service  rou¬ 
tine  used  for  short  sampling  periods  employes  the  CTC  exclusively.  The  routine 
for  longer  timing  periods  uses  a  sixteen  bit  counter  in  addition  to  the  CTC  timing. 
In  both  routines,  a  channel  selection  byte  is  written  to  the  AIO  board  to  initiate 
each  analog  to  digital  conversion.  The  final  CTC  related  software  accomplishes 
the  shut  down  of  the  interrupts.  These  shut  down  activities  are  also  in  the  Sam¬ 
pler  Module  portion  of  the  software. 

This  division  of  activity  between  the  Collect_Data  Module  and  the 
Sampler  Module  tracks  with  the  division  of  function  between  the  internal  data 
collection/storage  unit  and  the  external  control/long  term  storage  unit.  The  pro¬ 
gramming  values  needed  by  the  internal  unit  (Sampler  Module)  are  developed  in 
the  external  unit  (Collect_Data  Module)  and  passed  to  the  internal  unit  (Sampler 
Module)  to  program  the  data  collection.  Thus  the  software  developed  in  PLZ  for 
the  Collect_Data  Module  and  in  assembly  language  for  the  Sampler  Module 
reflects  the  dual-unit  hardware  concept  of  the  data  collection  system. 


Archival  Storage  of  Data  The  final  purpose  of  the  Collect  and 
Store  Data  process  is  the  transfer  of  data  from  its  temporary  storage  in  memory 
into  a  more  permanent  storage.  As  with  the  previous  two  discussions,  the  capa¬ 
bilities  available  in  the  MCZ  development  system  formed  the  basis  for  the  design. 
The  Zilog  system's  RIO  Operating  System  supports  disk  file  operations.  It  was 
pointless  to  reinvent  the  wheel  so  the  RIO  disk  file  operations  became  the  basis 
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for  the  long  term  data  storage.  In  the  PLZ  language  Collect_Data  Module,  a  disk 
file  is  created,  filled  with  the  data  from  memory,  and  then  closed.  To  satisfy  the 
requirements  for  data  integrity,  a  block  of  header  information  is  loaded  into  the 
beginning  of  the  raw  data  file.  This  header  information  holds  a  test  identifier,  a 
tag  which  all  subsequent  files  based  on  this  original  file  will  also  have.  This  tag  is 
ment  to  ensure  data  traceability. 

The  activities  of  the  Collect  and  Store  Data  process  are  thus  imple¬ 
mented  by  the  Collect_Data  Module  and  the  subordinate  Sampler  Module.  The 
combination  of  the  two  modules  represents  the  full  implementation  of  the  Collect 
and  Store  Data  process,  a  process  that  involves  both  the  internal  and  external 
units  of  the  target  data  collection  system.  Though  the  Collect_Data  Module  is 
subordinate  to  the  common  user  interface  process,  some  portions  of  the  common 
user  interface  are  implemented  in  Collect_Data  Module.  Co!lect_Data  Module 
sends  messages  to  the  user  and  performs  error  checking  on  the  user  supplied 
input  parameters.  Sampler  Module  also  has  one  direct  tie  to  the  user,  a  request 
for  a  begin  data  collection.  This  was  ment  to  simulate  a  trigger  signal. 


This  process  precedes  the  scaling  of  the  raw  data 
and  focuses  on  user  input  of  the  needed  scale  factors.  Though  interaction  with 
the  user  via  prompts  for  information  on  the  system  screen  and  keyboard  input  of 
data,  a  file  of  scale  factors  is  created.  The  scale  factor  file  holds  sixteen  records, 
one  for  each  of  the  input  channels  of  the  AIO  board.  The  user  interface  is  menu 
driven,  offering  the  user  a  choice  of  six  activities  associated  with  editing  the 
sixteen  records  of  the  scale  factor  file.  The  process  was  implemented  in  the 
Scale_Factor  Module.  This  PLZ  software  was  successfully  complied  but  due  to 
time  constraints  it  was  not  integrated  in  with  the  other  software.  The  listing  of 
Scale_Factor  Module  is  in  Appendix  B. 


The  purpose  of  this  process  is  to  translate  the  twelve  bit, 
two's  complement  representations  of  the  raw  data  file  into  scaled  data.  In  its 
simplest  form  this  would  be  accomplished  by  multiplying  each  channel’s  data  by 
the  appropriate  scale  factor  from  a  scale  factor  file.  This  process  was  not 
implemented. 
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This  process  simply  prints  out  the  contents  of  a  data  file. 
The  header  information  in  each  file  would  give  full  identification  of  the  original 
test  from  which  the  data  was  collected.  Similarly  the  channel  number,  sampling 
period,  number  of  samples,  and  user  comments  would  be  displayed  along  with 
the  data.  This  process  was  not  implemented. 


User  Data  Manipulations 

The  final  process  is  left  up  to  the  user's  needs.  However, 
to  maintain  data  integrity,  file  access  routines  which  included  the  necessary 
checks  and  prohibitions  would  be  provided  to  the  user.  With  these  routines,  the 
header  information  maintained  in  each  file  would  also  be  maintained  in  any  files 
created  by  user  activities.  These  process  support  routines  were  not  implemen¬ 
ted. 


Summary 

In  summary,  the  data  collection  system  was  partially  implemented  on 
a  Zilog  MCZ  Z-80  development  system.  The  data  collection  system  was  design¬ 
ed  around  five  processes  and  a  common  user  interface.  The  functions  of  the  in¬ 
ternal  data  storage  unit  were  implemented  in  the  assembly  language  Sampler 
Module.  Some  of  the  functions  of  the  external  data  storage  and  control  unit  were 
implemented  in  the  PLZ  language  Collect_Data  Module  and  its  subordinate 
Sampler  Module.  These  implementations  focus  on  the  Collect  and  Store  Data 
process.  Of  the  remaining  processes,  only  Set  Up  Scale  Factor  File  was  worked 
on,  it  being  implemented  in  the  Scale_Factor  Module. 


Overview  of  the  Rest  of  the  Thesis 


The  remainder  of  this  thesis  is  devoted  to  describing  the  software 
modules.  The  modules  are  presented  in  a  bottom  up  order.  The  modules' 
names  and  purposes  are  listed  below  along  with  the  page  numbers  for  the 
beginning  of  their  descriptions.  The  listings  of  module  software  are  in  the 
appendices. 
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Enhancements  20  Enhancements  Module  is  a  set  of  PLZ  language  rou¬ 
tines  which  make  input  and  output  in  PLZ  programs 
easier.  The  33  routines  are  divided  into  three  groups. 
There  are  20  "write"  routines,  8  "read"  routines,  and  10 
internal  support  routines.  Enhancements  Module  calls 
routines  of  the  PLZ.STREAM.IO  Module. 

Utility  124  Utility  Module  is  a  collection  nine  assembly  language 

routines  which  give  PLZ  language  routines  direct  ac¬ 
cess  to  10  ports,  memory  locations,  the  Z-80  interrupts, 
the  system  data,  and  the  operating  system  memory 
manager.  To  the  calling  PLZ  program,  these  assembly 
language  routines  look  just  like  PLZ  subroutines. 

Sampler  159  Sampler  Module  is  a  single  assembly  language  pro¬ 

gram  which  sets  up  and  executes  an  interrupt  paced 
analog  to  digital  conversion  data  collection  system. 
Sampler  Module  supports  the  PLZ  subroutine  call 
structures. 

Buffers  208  Buffers  Module  contains  no  code.  It  defines  a  2,000 

byte  memory  buffer  used  by  the  data  collection  system. 

Collect_Data  209  Co!!ect_Data  Module  is  a  PLZ  language  program  that 

controls  Sampler  Module's  collection  of  data  and  then 
loads  that  data  into  a  disk  file.  Co!lect_Data  must  be 
linked  with  the  Enhancements,  Sampler,  and  PLZ.¬ 
STREAM.IO  Modules.  Coilect_Data  Module  has  not 
been  compiled. 

AIO.PLZ.S  390  AIO.PLZ.S  Module  is  a  collection  of  PLZ  language  rou¬ 

tines  which,  through  Utility  Module  routines,  control  the 
AIO  analog  input  output  board  of  the  MCZ  development 
system.  These  routines  were  written  principally  as  de¬ 
sign  routines;  assembly  language  versions  are  in 
Sampler  Module. 

Sca!e_Factor  416  Scals_Factor  Module  is  a  PLZ  language  program 

through  which  the  user  would  set  up  or  edit  a  file  of 
scale  factors.  The  scale  factors  are  used  to  convert  raw 
data  files  into  scaled  data  files. 
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II.  Enhancements  Module 


Introduction  to  Enhancements  Module 

Enhancements  Module  is  a  collection  of  38  PLZ  language  routines 
whose  purpose  is  to  make  PLZ  input/output  more  Pascal-like.  The  20  "Write" 
routines  and  the  8  "Read"  routines  were  written  to  emulate  their  Pascal  name¬ 
sakes.  Internal  to  the  module  are  10  support  routines  used  for  data  formating, 
translation,  and  error  checking.  The  routines  are: 


■III  II  III  1  Ml  III  1  ■ 

ASCII 

WRITE 

READLN 

VALUE 

WRITELN 

READ  HBYTE 

VALUE  LOOP 

WRITE  DBYTE 

READ  DBYTE 

PUTCH 

WRITELN  DBYTE 

READ  BBYTE 

GETCH 

WRITE  HBYTE 

READ  LBYTE 

GET  ASCII  CH 

WRITELN  HBYTE 

READ  DINTEGER 

PLACE  LOOP 

WRITE  BBYTE 

READ  HWORD 

VALID  BINARY  CH 

WRITELN  BBYTE 

READ  DWORD 

VALID  DECIMAL  CH 

WRITE  LBYTE 

VALID  HEX  CH 

WRITELN  LBYTE 
WRITE  DINTEGER 
WRITELN  DINTEGER 
WRITE  DWORD 
WRITELN  DWORD 
WRITE  HWORD 
WRITELN  HWORD 
WRITE  POINTER 
WRITELN  POINTER 
WRITE  RCODE 
WRITELN  RCODE 

The  Enhancements  Module  routines  were  written  to  speed  up  devel¬ 
opment  of  other  PLZ  software,  to  make  PLZ  a  slightly  higher  level  language. 
Input/output  (10)  in  PLZ  is  somewhat  cumbersome.  For  example,  to  output  the 
string  "I  Like  Pascal  Best"  using  PLZ  10  the  statement  would  be: 

RETURN_BYTES,  RETURN_CODE  := 

PUTSEQ(  LOGICAL JJNIT,  ASTRING,  LENGTH  ) 

where  LOGICAL_UNIT  is  the  logical  unit  number  of  the  desired  output  device, 
ASTRING  is  a  pointer  to  the  string  "I  Like  Pascal  Best"  ("#'l  Like  Pascal  Best  %R'" 
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could  also  be  used  in  place  of  "ASTRING"),  and  LENGTH  is  the  number  of  chara¬ 
cters  to  be  output.  Thus,  unlike  Pascal's  single  input  parameter  for  WRITELN, 
PUTSEQ  requires  three  input  parameters.  Also  unlike  the  Pascal  WRITELN 
statement,  this  PLZ  output  has  two  output  parameters.  RETURN_BYTES  is  the 
number  of  character  actually  output  and  RETURN_  CODE  is  the  operating  system 
condition  or  error  code.  In  contrast,  using  the  Enhancements  Module  WRITELN 
procedure  the  line  is: 

WRITELN(  LOGICALJJNIT,  #'l  Like  Pascal  Best  %R') 

which  has  only  two  input  parameters  and  no  output  parameters.  This  is  possible 
because  the  Enhancements  Module  includes  the  procedures  necessary  to  check 
and  format  the  input,  eliminating  the  need  for  the  extra  parameters.  The  key  dif¬ 
ference  between  Pascal's  WRITELN  and  the  Enhancement's  Module  WRITELN  is 
the  manditory  inclusion  of  the  logical  unit  input  parameter.  In  Pascal,  the  output 
device  number  is  an  optional  parameter. 

The  logical  unit  parameter  was  incluaed  for  three  principal  reasons. 
First,  the  Enhancements  routines  are  compiled  appendages  to  the  PLZ  language, 
not  extensions  to  it.  Within  these  constraints,  it  simply  wasn't  possible  to  imple¬ 
ment  an  optional  parameter.  An  alternative  to  an  optional  parameter  would  be  a 
output  device  selection  function.  This  was  rejected  in  lue  of  the  logical  unit  para¬ 
meter  since  one,  Pascal  doesn't  have  such  a  function,  and  two,  it  would  increase 
the  overhead  of  the  Enhancements  Module,  including  the  addition  of  module 
level  variables.  The  third  reason  for  the  inclusion  of  the  logical  unit  parameter 
was  the  anticipation  that  many  devices  would  be  used  rendering  the  parameter 
particularly  useful.  For  these  reasons,  the  routines  of  the  Enhancements  Module 
include  the  logical  unit  parameter. 

The  other  major  deviation  from  Pascal  is  the  use  of  many  read  and 
write  statements  rather  than  just  four.  This  was  forced  by  the  appendage  nature 
of  the  Enhancements  Module  routines,  the  limitations  of  PLZ,  and  a  desire  to 
reduce  the  overhead  for  calling  routines.  In  Pascal,  the  output  string  is  parsed 
during  compillation;  PLZ  does  not  support  such  actions  during  compiling.  In 
Pascal,  variables  are  converted  to  or  from  ASCII  by  the  read  and  write  state¬ 
ments;  PLZ  does  not  support  such  conversions.  In  Pascal,  all  output  is  either 
decimal  representations  or  strings  of  ASCII  characters.  To  input  or  output  values 
in  other  than  decimal  representations  requires  the  Pascal  program  to  perform  the 
conversion.  By  having  separate  routines  already  set  up  for  10  in  ,  character  hexi- 
decimal,  decimal,  binary,  and  logical  formats,  the  burden  on  the  calling  PLZ  rou¬ 
tine  is  reduced.  Given  the  nature  of  the  Enhancements  Module,  the  restrictions  of 
PLZ,  and  the  desire  to  reduce  the  overhead  of  calling  routines,  separate  routines 
were  written  for  each  type  of  PLZ  variable. 

The  Enhancements  Module  routines,  as  appendages  to  PLZ,  do  use 
two  of  the  PLZ  input  output  routines  of  the  PLZ  STREAM.  10  Module  (Ref  6:  Sec 
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6).  These  routines,  PUTSEQ  and  GETSEQ,  are  the  primitive  input  and  output 
routines  upon  which  the  Enhancements  Module  routines  are  built.  PUTSEQ  and 
GETSEQ  are  declaired  external  to  the  Enhancements  Module.  Their  relationship 
to  the  Enhancements  Module  routines  is  shown  in  Figure  4. 


Any  PLZ  Routines  Needing  Input/Output  Support 


Figure  4.  Relationship  of  Enhancements  Module  Routines  to  Calling  PLZ 
Routines  and  to  PLZ  STREAM.  10  Module  Routines. 


To  show  how  the  Enhancements  Module  routines  can  be  used,  the 
following  are  some  examples  of  Pascal  10  statements  and  their  PLZ/Enhance- 
ments  Module  parallels.  Carriage  returns  in  the  output  are  shown  by  "%R"  is 
the  PLZ  constant  for  a  carriage  return. 


Example  1 
Pascal: 
Output: 
PLZ: 
Output: 


WRITELN(  This  is  a  Text  String  Output' ); 

This  is  a  Text  String  Output« 

WRITELN(  PRINTER,  #This  is  a  Text  String  Output  %R' ) 
This  is  a  Text  String  Output « 
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Example  2 

Pascal:  WRITE(  CURRENT_COUNT,  *  items  have  been  sorted.' ); 

Output:  27  items  have  been  sorted. 

PLZ:  WRITE_DBYTE(  PRINTER,  CURRENT_COUNT ) 

WRITE(  PRINTER,  #’  items  have  been  sorted.  %R' ) 

Output:  27.  items  have  been  sorted. 

Example  3 
Pascal* 

WRITELN(  DIMES, '  dimes  plus  \  NICKELS, '  nickels  totals  ’.TOTAL ); 
Output:  1 7  dimes  plus  8  nickels  totals  25« 

PLZ:  WRITE_DBYTE(  PRINTER,  DIMES  ) 

WRITE(  PRINTER,  #■  dimes  plus  %R' ) 

WRITE_DBYTE(  PRINTER,  NICKELS ) 

WRITE(  PRINTER,  #*  nickels  totals  %R' ) 

WRITELN_DBYTE(  PRINTER,  TOTAL ) 

Output:  17.  dimes  plus  8.  nickels  totals  25. « 

Example  4 

Pascal:  This  would  require  a  25+  line  routine,  including  a  16  item  case 

statement,  to  translate  the  decimal  variables  into  hex. 

PLZ:  WRITELN_HWORD(  PRINTER,  ADDRESS1  ) 

Output:  2FC7h 


Error  checking  is  both  accomplished  and  ignored  in  Enhancements 
Module  routines.  The  error  checking  that  is  performed  is  distributed  among  the 
routines.  Gross  errors,  like  an  operating  system  return  code  for  an  10  error,  are 
not  passed  back.  Errors  like  these  are  ignored  or  "patched"  to  permit  continued 
program  operation.  This  approach  was  selected  to  permit  the  programs  to  stum¬ 
ble  along  rather  than  fatally  fail  during  debugging.  This  way  debugging  can  pro¬ 
ceed  more  readily  using  the  expected  output  and  the  debugging  aid  of  WRITE_ 
RCODE  to  figure  out  what  went  wrong.  This  approach  is  based  on  the  belief  that 
once  final  version  software  was  reached  it  would  be  error  free  and  diagnostic 
error  checking  would  not  be  needed.  Defensive  error  checking,  such  as  GET_ 
ASCII_CH's  acceptance  of  only  ASCII  characters,  remains  in  place. 

To  give  an  example  of  the  distributed  error  checking,  the  figure  and 
text  below  describethe  process  of  reading  in  a  decimal  value  and  then  outputing 
it  as  a  hexidecimal  value.  This  process  involves  thirteen  routines,  seven  for  input 
and  six  for  output.  The  routines  involved  and  their  relationship  is  shown  in  Figure 
5  .  Error  checking  and  ignoring  is  scattered  throughout  the  thirteen  routines. 
The  following  is  a  list  of  the  error  related  actions. 
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1.  GETSEQ  This  is  an  external  routine  of  the  PL Z  STREAM.IO  Module.  It 

returns  to  a  calling  routine  the  RIO  operating  system  error  code, 
RETURN_CODE,  and  the  number  of  characters  actually  read  in, 
LENGTH. 

2.  GETCH  This  routine  calls  GETSEQ  to  read  in  only  one  character. 

GETCH  then  ignores  the  return  parameter  LENGTH  since  only 
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3.  GET_ASCII_CH  Only  ASCII  characters  are  returned  to  the  calling  routine 

by  GET_ASCII_CH.  It  checks  the  character  it  gets  from  GETCH 
to  see  whether  it  is  a  valid  ASCII  character.  If  it  is,  the  character 
is  returned  to  the  calling  routine.  If  not,  GET_ASCII_CH  calls 
GETCH  for  another  character  and  keeps  checking  and  callin 
GETCH  until  a  valid  ASCII  character  is  read. 

4.  READ_DWORD  This  routine  does  no  error  checking  itself.  It  depends  upon 

GET_  ASCII_CH  to  pass  only  valid  ASCII  characters  and  upon 
VALID_DECIMAL_CH  to  ok  only  "0"  through  "9".  READ_ 
DWORD  sits  in  a  loop,  calling  GET_ASCII_CH  and  VALID_ 
DECIMAL_CH  until  sufficient  characters  are  input.  Then  READ_ 
DWORD  depends  upon  VALUE_  LOOP  to  correctly  translate  the 
characters,  all  already  verified  as  decimal,  into  the  NUMBER 
passed  back  to  the  calling  routine. 

5.  VALID_DECIMAL_CH  VALID_DECIMAL_CH  examines  the  characters 

passed  to  it.  If  the  character  is  a  "0"  through  "9"  VALID_ 
DECIMAL_CH  returns  as  TRUE,  otherwise  it  returns  as  FALSE. 

6.  VALUE  This  routine  is  used  by  VALUE_LOOP  to  translate  a  character 

into  the  MAGNITUDE  it  represents.  VALUE  will  translate  the 
characters  "0"  through  "P  into  values  of  0  through  16.  If  VALUE 
does  receive  a  character  other  than  these  defined,  it  returns  a 
MAGNITUDE  of  zero. 

7.  VALUE_LOOP  With  the  MAGNITUDES  returned  from  VALUE,  VALUE_ 

LOOP  translates  the  string  of  characters  into  a  single 
MAGNITUDE.  VALUE_  LOOP  checks  for  overflow  with  the 
addition  of  each  character's  contribution  to  the  total  value.  If 
overflow  is  detected,  the  output  MAGNITUDE  is  set  to  the 
maximum  possible  for  a  PLZ  word,  65535  decimal. 

At  this  point,  READ_DWORD  returns  NUMBER  to  its  calling  routine.  For  this 
example,  NUMBER  is  immediately  passed  to  WRITELN_HWORD. 

8.  WRITELNJHWORD  This  routine  depends  upon  WRITE_HWORD  and 

PUTCH  to  handle  errors  and  expects  its  calling  routine  to  pass 
only  valid  NUMBERS  to  be  output. 

9.  WRITE_HWORD  This  routine  does  no  error  checking.  It  depends  upon 

PLACE_  LOOP  to  translate  NUMBER  into  ASCII  characters  and 
PUTCH  to  output  the  "h".  It  also  expects  its  calling  routine  to 
pass  only  valid  NUMBERS. 

10.  PLACE_LOOP  This  routine  also  does  no  error  checking.  It  breaks  down 
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the  NUMBER,  from  most  significant  place  to  the  ones  place, 
determining  the  VALUE  of  each  place.  PLACE_LOOP  depends 
upon  ASCII  to  correctly  translate  the  VALUES  into  ASCII 
characters  and  upon  PUTCH  to  output  those  characters. 


1 1 .  ASCII  Through  the  use  of  a  case  statement  ASCII  translates  VALUES  ;3 

into  CHARACTERS.  If  the  value  passed  exceeds  16  decimal,  jj 

ASCII  returns  a  blank.  Thus  if  any  of  the  higher  lever  routines  jfj 

errored,  ASCII  will  return  either  a  blank  or  an  erroneous  ;$ 

character  between  "0"  and  "P.  Thus,  the  program  will  continue 
to  execute  though  flawed  output  may  occur.  ;! 


12.  PUTCH  This  routine  ignores  all  errors  returned  by  PUTSEQ.  PUTCH 

calls  PUTSEQ  to  output  only  one  character.  PUTCH  assumes 
that  the  single  character  is  successfully  output.  PUTCH  also 
ignores  the  PUTSEQ  output  parameter  RETURN_CODE 
assuming  that  the  output  was  successful.  This  permits  the 
program  to  continue  execution. 

13.  PUTSEQ  This  is  an  external  routine  of  the  PLZ  STREAM.IO  Module.  Its 

error  checking  has  two  return  parameters,  the  RIO  operating 
system  RETURN_CODE,  and  the  number  of  characters  actually 
output,  LENGTH. 


'A 


While  Enhancements  Module  is  a  complete  set  of  10  support  routines 
intended  to  ease  the  10  programming  in  PLZ,  not  all  PLZ  applications  will  require 
all  of  the  routines.  In  these  cases,  a  new  module,  containing  only  the  needed 
routines  could  be  formed  and  linked  in  with  the  application  program.  An  example 
of  such  a  module,  DEBUGS,  is  listed  in  Appendix  A.  Alternatively,  the  Enhance¬ 
ments  routines  needed  could  be  part  of  the  calling  routine’s  module.  An  example 
of  this  approach  is  Scale_Factor  Module  (Appendix  H).  In  either  case,  the  PLZ 
STREAM.IO  must  be  linked  in  for  access  to  PITSEQ  and  GETSEQ. 

If  speed  of  execution  is  of  concern,  the  overhead  of  the  Enhancements 
Module  routines  could  be  reduced  by  combining  the  code  of  several  routines  into 
one  larger  routine.  This  would  eliminate  the  overhead  and  delay  of  subroutine 
calls  present  in  the  current  set  of  routines.  For  example  the  six  routines  used  in 
the  example  above  to  read  in  a  decimal  value  could  be  combined  into  a  single 
routine  version  of  READ_DWORD.  The  negative  impact  of  this  approach  would 
be  the  duplication  of  many  lines  of  code  in  the  combined  routines. 

In  conclusion,  the  38  PLZ  routines  of  the  Enhancements  Module  were 
A  written  to  make  10  in  PLZ  a  little  easier,  in  effect  to  make  PLZ  a  slightly  higher 

level  language.  These  routines  have  defensive  error  checking  distributed 


r. 

r. 


y. 
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throughout  the  routines  but  patch  or  ignore  fatal  errors  in  the  belief  that  a  routine 
that  stumbles  along  is  easier  to  debug  than  one  which  fails  completely.  Though 
the  Enhancements  Module  is  a  complete  set  of  IO  routines,  not  all  applications 
will  require  all  38  routines.  In  these  cases,  a  module  of  selected  routines  could 
be  used  or  the  routines  needed  could  be  put  into  the  application  program's  mod¬ 
ule.  In  either  case  the  PLZ  STREAM. 10  Module  must  be  linked  in. 


The  following  pages  detail  the  38  Enhancements  Module  routines. 

For  each  routine  the  documentation  includes: 

1 .  Name  of  the  routine  or  routines, 

2.  Name  of  module, 

3.  Language  routine  is  witten  in  and  number  of  lines  of  code, 

4.  A  synopsis  of  the  routine  or  routines, 

5.  A  data  flow  diagram  showing  the  relationship  of  the  routine  to  its 
calling  routines  and  to  routines  it  calls, 

6.  How  the  routine  is  invoked  including  the  input  parameter  passing 
schema  and  a  list  of  the  routines  which  call, 

7.  The  variables  and  constants  used  by  the  routine  at  the  global, 
module,  and  routine  level, 

8.  The  names,  purpose,  invocation,  and  parameter  passing  of  any 
other  routines  called  by  the  routine, 

9.  The  output  of  the  routine  and  any  system  configuration  changes 
produced  by  the  routine, 

1 0.  The  testing  of  the  routine  and  the  results  of  the  testing,  and 

1 1 .  The  location  of  the  program  listing. 


The  program  listings  for  Enhancements  Module  and  the  various  test 
routines  are  in  Appendix  A.  Further  information  on  the  PLZ  language  can  be 
found  in  references  five  and  six. 
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1.  Name  of  Routine:  ASCII 

2.  Internal  routine  of  Enhancements  Module. 

3.  Written  in  PLZ;  22  lines  of  executable  code. 


ASCII  is  an  internal  support  routine  of  the  Enhancements  Module.  It  trans¬ 
lates  a  hexadecimal  value  (0  through  F)  into  the  ASCII  character  which  repre¬ 
sents  that  value  {"0"  through  "F).  To  facilitate  the  use  of  leading  blanks  in  stings 
of  values,  ASCII  will  return  a  blank  (ASCII  20  hex)  rather  than  a  zero  (ASCII  30 
hex)  if  blanking  is  selected. 


Figure  6.  Relationship  of  ASCII  to  PLACE_LOOP. 


a.  Invocation  Statement 


ASCII  is  invoked  by: 

OUT_BLANKING,  CHARACTER  :=  ASCII  (  VALUE,  IN_BLANKING  ) 


b.  Parameter  Passing  Schema 

ASCII  has  two  input  parameters,  VALUE,  type  Word,  and  IN_BLANK- 
ING,  type  Byte.  VALUE  is  the  hexadecimal  quantity  that  is  to  be  translated  into 
the  correct  ASCII  character.  IN_BLANKING  is  a  logical  parameter  which  indi¬ 
cates  wether  values  of  zero  should  be  returned  as  a  "0",  when  IN_BLANKING  is 
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false,  or  as  a  blank,  when  IN_BLANKING  is  true.  The  output  parameters  are 
discussed  below. 


c.  Routines  Which  Call  ASCII 

ASCII  is  an  internal  support  routine  for  Enhancements  Module  was 
written  to  be  called  only  by  PLACE_LOOP,  another  internal  routine  of  Enhance¬ 
ments  Module. 


ASCII  uses  no  globally  defined  constants  or  variables. 


b.  Module 

ASCII  uses  three  Enhancements  Module  constants: 
TRUE:  Value  of  1 ,  logical  true, 

FALSE:  Value  of  0,  logical  false,  and 
BLANK:  Value  20  hex,  ASCII  blank  character. 


ASCII  calls  no  other  routines. 


a.  Parameter  Passing  Schema 

ASCII  has  two  output  parameters,  CHARACTER  and  OUT_  BLANK¬ 
ING,  both  of  type  Byte.  CHARACTER  is  returned  as  the  ASCII  character  which 
represents  the  VALUE  input  to  the  routine.  However,  if  IN_BLANKING  was  True 
and  VALUE  was  zero,  CHARACTER  will  be  returned  as  a  blank  (ASCII  20  Hex). 
OUT_BLANKING  is  a  logical  parameter,  true  if  CHARACTER  is  returned  as  a 
blank,  false  otherwise.  OUT_BLANKING  is  a  flag  to  the  calling  routine  that  a 
blank  was  returned. 
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b.  System  Configuration  Changes 


ASCII  causes  no  system  changes. 


10.  Routine  Testing 

a.  Description  of  Test 

ASCII  was  tested  in  combination  with  its  calling  routine  (PLACE_ 
LOOP)  and  the  hexidecimal  output  routines  WRITE_HBYTE  and  WRITELN_ 
HBYTE.  The  PLZ  program  output  hexadecimal  characters  to  the  system  console. 
Out  of  range  and  undefined  values  were  used  in  addition  to  a  range  of  valid 
values.  Unless  all  routines  were  working,  no  output  would  occur. 


b.  Results  of  Test 

The  proper  characters  were  output  to  the  system  console  for  all  cases 

tested. 

11.  Reference  to  Listing 

ASCII's  listing  is  on  page  280  in  Appendix  A. 


( 


r 
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1 .  Routine  Name:  VALUE 


2.  Part  of  Enhancements  Module 

3.  Written  in  PLZ.  19  lines  of  executable  code. 

4.  Synopsis  of  Routine 

VALUE  is  an  internal  support  routine  of  the  Enhancements  Module.  It 
is  used  to  convert  from  ASCII  characters  (0  to  9  and  A  to  F)  into  their  hexadeci¬ 
mal  values.  If  an  undefined  character  is  passed,  a  value  of  0  hex  is  returned. 
VALUE  supports  some  of  the  READ  statements  of  the  Enhancements  Module. 


5.  Routine  Relationships  Diagram 


VALUE  LOOP  READ  HBYTE  READ  DBYTE 


\  I  / 

|  VALUE  | 


Figure  7.  Relationship  of  VALUE  to  Other  Routines. 


6.  Invocation 

a.  Invocation  Statement 

VALUE  is  invoked  via: 

MAGNITUDE  :=  VALUE(  CHARACTER  ) 
where  CHARACTER  and  MAGNITUDE  are  both  of  type  Byte. 

b.  Parameter  Passing  Schema 

VALUE  has  one  input  parameter,  CHARACTER,  the  ASCII  character 
that  is  to  be  translated  into  a  hexidecimal  value. 
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c.  Routines  Which  Call  VALUE. 

VALUE  is  an  internal  support  routine  of  the  Enhancements  Module,  it 
was  written  to  be  called  only  by  VALUE_LOOP,  READ_HBYTE,  and  READ_ 
DBYTE. 


VALUE  uses  no  constants  or  variables  outside  of  its  input  and  output 
parameters. 


VALUE  calls  no  other  routines. 


a.  Parameter  Passing  Schema 

VALUE  has  a  single  output  parameter,  MAGNITUDE,  the  hexidecimal 
value  represented  by  the  input  parameter  CHARACTER. 


b.  System  Configuration  Changes 

VALUE  causes  no  system  configuration  changes. 


a.  Description  of  Test 

VALUE  was  tested  in  concert  with  VALUE_LOOP,  READJHBYTE,  and 
READ_DBYTE.  A  short  PLZ  program  read  in  values  from  the  keyboard  and  out¬ 
put  their  value  to  the  system  console.  Out  of  range  and  undefined  values  were 
also  input.  Unless  all  the  routines  worked,  proper  output  would  not  occur. 


b.  Results  of  Test 


input. 


The  correct  values  were  output  including  when  improper  values  were 
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VALUE'S  listing  is  on  page  281  in  Appendix  A. 
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1.  Routine  Name:  VALUE_LOOP 

2.  Internal  routine  of  Enhancements  Module. 


v; 

►j 


k. 


[**. 


3.  Written  in  PL Z;  1 1  lines  of  executable  code. 

4,  Synopsis  of  Routine 

VALUE_LOOP  is  an  internal  support  routine  of  the  Enhancements 
Module;  it  is  used  by  some  of  the  READ  routines.  VALUE_LOOP  translates  a 
string  of  ASCII  characters  into  the  value  they  represent.  The  string  of  ASCII 
characters  (1  to  8  characters)  can  be  in  any  base  as  the  base  is  input  to 
VALUE_LOOP.  The  routine  translates  each  character  into  a  value  (via  routine 
VALUE),  multiplies  that  value  by  the  base  factor  for  that  character’s  position,  and 
then  adds  the  character’s  full  value  to  the  cumulative  value.  This  process  begins 
with  the  least  significant  bit  and  proceeds  through  the  higher  significence  bits.  If 
the  translated  value  exceeds  the  maximum  value  for  a  PLZ  word  (65535  decimal) 
the  output  value  is  set  to  the  maximum.  The  routine  ends  when  a  blank  is 
detected  or  when  eight  characters  have  been  translated. 


5,  Routinfi^glationship  Diagram 


Figure  8.  Relationship  of  VALUE_LOOP  to  Other  Routines. 


6.  Invocation 

a.  Invocation  Statement 

VALUE  LOOP  is  called  via: 


Enhancements  Module 


34 


MAGNITUDE  :=  VALUE_LOOP(  INPUT_STRING,  MULTIPLIER  ) 

where  MAGNITUDE  and  MULTIPLER  are  of  type  Word  and  INPUT_STRING  is  a 
pointer  to  an  ASCII  string. 


b.  Input  Parameter  Passing  Schema 

VALUE_LOOP  has  two  input  parameters.  INPUT_STRING  is  a  pointer 
to  the  string  of  ASCII  characters  to  be  translated.  MULTIPLER  is  the  base  of  the 
number  represented  by  the  string  of  characters.  As  it  is  type  Word  it  has  a  de¬ 
fined  range  of  0  to  65535  decimal  though  its  useful  range  is  2  to  1 6  decimal. 


c.  Routines  Which  Call  VALUE_LOOP 

VALUE_LOOP  is  an  internal  support  routine  of  the  Enhancements 
Module.  It  was  written  to  be  called  only  by  READ_BBYTE,  READ_DINTEGER, 
READ_HWORD,  and  READ_DWORD.  This  is  important  as  error  checking  is 
distributed  among  the  routines. 


7.  Variables  and  Constants 

a.  Global 

VALUE  LOOP  uses  no  module  level  variables  or  constants. 


b.  Module 

VALUE_LOOP  uses  one  module  level  constant,  BLANK:  The  ASCII 
value  20  hex  for  a  blank.  VALUE  LOOP  uses  no  module  level  variables. 


c.  Routine 

VALUE_LOOP  uses  two  routine  level  variables,  INDEX  and  FACTOR. 
INDEX,  type  byte,  is  used  to  advance  through  the  input  character  string.  Its  initial 
value  is  zero.  FACTOR,  type  word,  holds  the  base  value  of  the  current  character 
position.  It  is  the  base  (MAGNITUDE)  raised  to  the  INDEX  power.  Its  initial  value 
is  one. 
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VALUE_LOOP  calls  procedure  VALUE  to  translate  each  character  into 
the  value  it  represents.  VALUE  is  also  an  internal  support  routine  of  Enhance¬ 
ments  Module.  VALUE  is  invoked  via: 

MAGNITUDE  :=  VALUE(  CHARACTER  ) 

where  CHARACTER  is  the  ASCII  character  to  be  converted  into  the  MAGNITUDE 
it  represents.  Both  CHARACTER  and  MAGNITUDE  are  of  type  Byte. 


9.  Output  of  Routine 

a.  Output  Parameter  Passing  Schema 

VALUE_LOOP  has  one  output  parameter,  MAGNITUDE,  of  type  Word. 
It  is  the  value  represented  by  the  input  character  string  of  the  input  base.  MAGNI¬ 
TUDE  can  take  on  a  value  of  0  to  65535  decimal.  If  the  value  of  the  input  string 
exceeds  the  maximum  value,  the  maximum  value  will  be  returned. 


b.  System  Configuration  Changes 

VALUE_LOOP  causes  no  system  configuration  changes. 


IQ,  Routine  Testing 

a.  Description  of  Test 

VALUE_LOOP  was  tested  along  with  other  Enhancements  Module 
routines.  The  complete  set  of  routines  are  necessary  for  correct  function.  The 
integrating  PLZ  program  read  in  character  strings  from  the  keyboard,  translated 
their  value  (using  VALUE_LOOP  and  VALUE),  and  then  output  the  value  to  the 
system  console.  Various  valid  character  strings  and  several  out  of  range  and 
invalid  strings  were  input. 


b.  Results  of  Test 

The  correct  value  was  output  to  the  console  for  all  cases  tested. 
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1.  Routine  Name:  PUTCH 


2.  Internal  routine  of  Enhancements  Module. 

3.  Written  in  PLZ;  three  executable  lines  of  code. 

4.  Synopsis  of  Routine 

PUTCH  is  an  extremely  short  routine  which  interfaces  the  output  routines  of 
Enhancements  Module  with  the  output  routine  of  the  PLZ  Stream  10  Module, 
PUTSEQ.  Where  PUTSEQ  has  five  parameters  (three  input  and  two  output), 
PUTCH  as  only  two  input  parameters.  PUTCH  thus  insulates  the  output  rou¬ 
tines  of  the  Enhancements  Module  from  the  added  complexities  of  PUTSEQ. 
PUTCH  is  based  on  a  sample  routine  given  the  the  PLZ  Documentation  (Ref  6: 
6-5). 


5.  Routine  Relationships  Diagram 


Enhancements  Module  Routines 

WRITE  XXXX  &  WRITELN  XXXX 


PUTCH 


c 


PUTSEQ 


PLZ  STREAM.IO 
Module 


J 


Figure  9.  Relationship  of  PUTCH  to  Other  Routines. 


5,  invQcation 

a.  Invocation  Statement 

PUTSEQ  is  invoked  as  follows. 

PUTCH(  LOGICAL_UNIT,  CHARACTER ) 
where  both  input  parameters  are  of  type  Byte. 
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b.  Parameter  Passing  Schema 


PUTCH  has  two  input  parameters.  LOGICALJJNIT  is  the  number  of 
the  device  the  output  is  to  be  routed  to.  CHARACTER  is  the  value  to  be  output  to 
the  desired  LOGICALJJNIT.  Though  its  name  implies  ASCII  data,  any  eight  bit 
hexidecimal  value  can  be  passed  though  CHARACTER. 


c.  Routines  Which  Call  PUTCH. 

PUTCH  is  an  internal  support  routine  of  the  Enhancements  Module.  It 
was  written  to  be  called  only  by  Enhancement  Module  routines.  PUTCH  is  called 
by  PLACE_LOOP,  WRITELN,  WRITE  JJBYTE,  WRITELN  JDBYTE,  WRITE_ 
HBYTE,  WRITELN  JHBYTE,  WRITE J3BYTE,  WRITELN_BBYTE,  WRITELN_ 
LBYTE,  WRITEJDINTEGER,  WRITELN  JDINTEGER,  WRITE JDWORD,  WRITELN_ 
DWORD,  WRITE JHWORD,  WRITELN_HWORD,  and  WRITELN_POINTER. 


a.  Global 


PUTCH  uses  no  global  variables  or  constants. 


b.  Module  Level 


PUTCH  uses  no  module  level  variables  or  constants. 


c.  Routine  Level 

Within  the  routine  are  two  variables,  LENGTH  (type  Word)  and 
RETURN_CODE  (type  Byte).  LENGTH  is  used  as  both  for  input  and  output 
parameters  to  the  external  routine  PUTSEQ.  For  input  it  is  set  to  one  as  PUTCH 
outputs  only  one  byte  to  PUTSEQ.  LENGTH  is  used  as  a  place  keeper  output 
variable  -  there  only  to  keep  the  subroutine  calling  syntax  correct.  RETURN_ 
CODE  is  similarly  used  as  a  place  keeper  output  parameter. 


PUTCH  calls  PUTSEQ,  an  external  routine  of  the  PLZ  STREAM  10 
Module.  PUTSEQ  outputs  a  known  length  sequence  of  values  to  the  specified 
logical  unit.  PUTSEQ  is  invoked  by: 
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LENGTH,  RETURN_CODE  := 

PUTSEQ(  LOGICAL_UNIT,  BUFFER_PTR,  LENGTH  ) 

PUTSEQ  has  three  input  parameters,  LOGICAL_UNIT,  BUFFER_PTR, 
and  LENGTH.  LOGICALJJNIT  (type  Byte)  is  the  number  of  the  device  to  which 
data  is  to  be  output.  BUFFER_PTR  (type  Pointer  to  Byte)  is  a  pointer  to  the  string 
of  characters  (or  values)  to  be  output  to  the  designated  logical  unit.  Note  that  as 
PUTCH  outputs  only  single  characters,  BUFFER_PTR  is  passed  as  pointer  to  the 
PUTCH  input  parameter  CHARACTER.  Thus,  in  the  call  to  PUTSEQ, 
CHARACTER  undergoes  a  type  conversion  from  Byte  to  Pointer-to-Byte.  The 
third  input  parameter,  LENGTH  (type  Word),  is  the  number  of  characters  (values) 
to  be  output;  the  length  of  the  string  pointed  to  by  BUFFER_PTR.  The  PUTSEQ 
call  in  PUTCH  uses  the  constant  one  for  LENGTH  as  only  a  single  character  is 
output. 


PUTSEQ  returns  two  parameters,  LENGTH  and  RETURN_CODE. 
LENGTH  (type  Word)  is  the  number  of  bytes  actually  output.  RETURN_CODE  is 
the  operating  system  error  code. 


9.  Output  of  Routine 

PUTCH  has  no  output  parameters.  Beyond  writing  a  value  to  a  logical 
unit,  PUTCH  has  no  impact  on  system  configuration. 


10.  Routine  Testing 

PUTCH  was  not  specifically  tested.  Rather,  it  was  tested  along  with 
the  other  routines  of  the  Enhancements  Module.  Most  of  the  "write"  and  "writeln" 
routines  use  PUTCH,  directly  or  indirectly.  These  routines  worked,  thus  PUTCH 
worked. 


11.  Reference  to  Listing 

The  listing  for  PUTCH  is  on  page  283  in  Appendix  A. 


Enhancements  Module 


40 


1.  Routine  Name:  GETCH 


2.  Internal  routine  of  Enhancements  Module. 

3.  Written  in  PL 2;  four  lines  of  executable  code. 


4.  Synopsis  of  Routine 

GETCH  is  a  very  simple  routine  which  interfaces  the  PLZ  STREAM  10 
Module  routine  GETSEQ  to  the  "read"  routines  of  the  Enhancements  Module. 
Where  GETSEQ  has  three  input  parameters  and  two  output  paramenters, 
GETCH  presents  its  calling  PLZ  routine  with  one  input  and  one  output  para¬ 
meter.  The  key  difference  is  that  GETSEQ  can  read  in  a  string  of  arbitrary  length 
while  GETCH  reads  in  a  single  value.  GETCH  is  based  on  a  sample  routine 
given  the  the  PLZ  Documentation.  (Ref  6: 6-5) 


5.  Routine  Relationships  Diagram 


READ. 
READ  BBY 

'1 

DINTEGER  READ_HWORD 

TE  ^  j  READ_DWORD 

GETCH  \ 

r  1  pct^a"  PLZ  STREAM.IO  ^ 

[  1  GETSEQ  Module 

Figure  10.  Relationship  of  GETCH  to  Other  Routines 


6,  Invocation 

a.  Invocation  Statement 
GETCH  is  invoked  by: 

CHARACTER  :=  GETCH(  LOGICALJJNIT) 
where  both  CHARACTER  and  LOGICALJJNIT  are  of  type  Byte. 
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b.  Parameter  Passing  Schema 

GETCH  uses  the  input  parameter  LOGICAL_UNIT  to  select  the  device 
from  which  a  value  is  to  be  read.  The  value  read  is  output  via  parameter 
CHARACTER.  Despite  its  name,  CHARACTER  could  output  any  eight  bit  value. 


c.  Routines  Which  Call  GETCH. 

GETCH  is  an  internal  routine  of  the  Enhancements  Module  and  was 
written  to  be  called  only  by  other  Enhancements  Module  routines.  GETCH  is 
called  by  GET_ASCII_CH. 


7.  Variables  and  Constants 

a.  Global  Level 

GETCH  uses  no  global  variables  or  constants. 


b.  Module  Level 

GETCH  uses  no  module  level  variables,  it  does  use  two  module  level 
constants,  OPERATION_OK  and  BLANK.  OPERATION_OK  is  the  operating  sys¬ 
tem  return  code  for  a  successful  10  action;  its  value  is  80  hexidecimal.  BLANK  is 
the  ASCII  blank,  value  20  hexidecimal. 


c.  Variables  and  Constants  internal  to  GETCH 

GETCH  has  two  internal  variables  and  one  internal  constant.  The 
internal  variables,  RETURN_CODE  (type  Byte)  and  LENGTH  (type  Word),  are 
used  in  calling  GETSEQ.  The  constant  used,  1,  is  explicit  (not  a  named  con¬ 
stant)  and  is  also  used  in  calling  GETSEQ. 


8.  Other  Routines  Called 

GETCH  calls  a  single  routine,  GETSEQ,  an  external  routine  of  the  PLZ 
STREAM. 10  Module.  GETCH  uses  GETSEQ  to  read  a  single  character  from  a 
designated  logical  unit.  GETSEQ  has  one  input  parameter,  LOGICALJJNIT 
(type  Byte);  one  return  parameter,  RETURN_CODE  (type  Byte);  and  two  bidirec¬ 
tional  parameters,  BUFFER_PTR  (type  Pointer-to-Byte)  and  LENGTH  (type 
Word).  LOGICALJJNIT  passes  the  number  of  the  device  driver  from  which  the 
character  will  be  taken.  This  is  the  same  as  the  LOGICALJJNIT  passed  into 
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GETCH.  RETURN_CODE  carries  back  the  operating  system  code  indicating 
whether  the  input  was  successful  or  not.  If  RETURN_CODE  does  not  pass  back 
the  OPERAT!ON_OK  code,  GETCH  returns  to  its  calling  routine  a  blank. 

BUFFER_PTR  points  the  the  memory  location  where  the  first  character 
of  the  string  will  be  stored.  Thus,  it  is  similar  in  function  but  different  in  type  from 
the  GETCH  input  parameter  CHARACTER.  In  the  invocation  of  of  GETSEQ, 
BUFFER_PTR  is  passed  CHARACTER  or  pointer  to  the  variable  CHARACTER, 
type  Pointer-to-Byte.  In  this  way  the  type  conversion  occurs. 

LENGTH  serves  two  purposes.  On  the  call  to  GETSEQ,  LENGTH 
gives  the  number  of  characters  which  are  supposed  to  be  read  in.  Upon  return  to 
GETCH,  LENGTH  passes  back  the  number  of  characters  actually  read.  For 
GETCH,  LENGTH  is  passed  to  GETSEQ  with  the  constant  value  of  1  as  a  single 
character  is  to  be  output;  the  return  value  of  LENGTH  is  ignored. 

GETSEQ  is  invoked  via: 

LENGTH,  RETURNjCODE  := 

GETSEQ(  L0G1CAL_UNIT,  CHARACTER,  LENGTH  ) 


GETCH  returns  to  its  calling  routine  a  single  ASCII  character  in  the 
output  parameter  CHARACTER  (type  Byte).  If  the  reading  operation  was  unsuc¬ 
cessful  for  any  reason,  a  blank  is  returned  to  the  calling  routine.  Beyond  reading 
a  character  in  from  a  logical  unit,  GETCH  causes  no  system  configuration 
changes. 


a.  Description  of  Test 


GETCH  was  tested  with  the  rest  of  the  Enhancements  Module 

routines. 


b.  Results  of  Test 

GETCH  worked  properly. 
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1.  Routine  Name:  GET_ASCH_CH 

2.  Internal  routine  of  Enhancements  Module. 

3.  Written  in  PL Z;  three  lines  of  executable  code. 

4.  Synopsis. of  Routine 

GET_ASCII_CH  reads  in  values  from  a  designated  logical  unit  and 
checks  that  the  value  read  in  is  a  valid  ASCII  character.  If  the  value  is  valid,  the 
character  is  returned  to  the  calling  PLZ  routine.  Otherwise,  GET_ASCII_CH 
keeps  reading  in  values  until  a  valid  character  is  read.  The  values  GET_ 
ASCII_CH  considers  valid  are: 

All  printing  characters:  0-9,  a-z,  A-Z,  and  punctuation, 

Control-G,  the  aural  tone, 

Control-1,  horizonal  tab, 

Control-J,  line  feed, 

Control-M,  carriage  return, 

Control-[,  escape,  and 
blank. 


5.  Routine  Relationships  Diagram 


Figure  1 1 .  Relationship  of  GET_ASCII_CH  to  Other  Routines. 


6.  Invocation 

a.  Invocation  Statement 

GET  ASCII  CH  is  invoked  via: 
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CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT ) 
where  both  CHARACTER  and  LOGICAL_UNIT  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

The  input  parameter  LOGICAL_UNIT  is  used  to  designate  which 
device  the  value  is  to  be  read  from. 


c.  Routines  Which  Call  GET_ASCII_CH. 

GET_ASCI!_CH  is  an  internal  routine  of  Enhancements  Module  and 
was  written  to  be  called  only  by  other  Enhancements  Module  routines.  GET_ 
ASCII_CH  is  called  by  READLN,  READ_HBYTE,  READ_DBYTE,  READ_BBYTE, 
READ_LBYTE,  READ_DINTEGER,  READ_HWORD,  and  READ_DWORD. 


7.  Variables  and  Constants 

a.  Global 

Aside  for  the  definitions  for  ASCII  characters,  GET_ASCII_CH  uses  no 
gloal  variables  or  constants. 


b.  Module  Level 


Within  the  Enhancements  Module,  a  number  of  constants  are  used  to 
represent  nonprinting  ASCII  characters.  GET_ASCII_CH  uses: 


BELL: 

TAB: 

LINE_FEED: 

CARRIAGE_RETURN: 

ESCAPE: 

BLANK: 


ASCII  Control-G,  the  aural  tone, 
ASCII  Control-1,  horizonal  tab, 
ASCII  Control-J, 

ASCII  Control-M, 

ASCII  Control-[,  and 
ASCII  for  a  space. 


GET_ASCII_CH  uses  no  module  level  variables. 


c.  Routine  Level 

GET_ASCU_CH  has  no  routine  level  variables  or  constants. 
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GET_ASCI1_CH  uses  another  Enhancements  Module  routine, 
GETCH,  to  read  a  character  from  the  device  designated  by  the  input  parameter 
L0GICAL_UN1T  (type  Byte).  If  the  reading  operation  was  successful,  GETCH 
re-turns  the  ASCII  character  in  return  parameter  CHARACTER  (type  Byte).  If  the 
reading  operation  was  unsuccessful,  GETCH  returns  a  blank.  GETCH  is  invoked 
via: 


CHARACTER  :=  GETCH(  LOGICALJJNIT ). 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

GET_ASCII_CH  has  one  output  parameter,  CHARACTER  (type  Byte) 
which  returns  an  ASCII  character  to  the  calling  routine. 


b.  System  Configuration  Changes 

Beyond  reading  in  one  or  more  values  from  the  designated  logical 
unit,  GET_ASCI1C_CH  causes  no  system  configuration  changes. 


IQ.  Routing  Testing 

a.  Description  of  Test 

GET_ASCII_CH  was  not  tested  independently.  It  was  tested  in  con¬ 
cert  with  the  "read"  routines  of  the  Enhancements  Module.  All  of  the  read  rou¬ 
tines  use  GET_ASCII_CH  to  input  characters.  Thus,  any  test  of  these  read  rou¬ 
tines  tests  GET_ASCII_CH. 


b.  Results  of  Test 

The  "read"  routines  of  the  Enhancements  Module  functioned  properly. 
Thus  GET_ASCII_CH  works  properly. 

11.  Reference  to  Listing 

GET_ASCII_CH’s  program  listing  is  on  page  284  in  Appendix  A. 
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1.  Routine  Name:  PLACE_LOOP 

2.  Internal  routine  of  Enhancements  Module. 


3.  Written  in  PL Z;  seven  lines  of  executable  code. 


4.  Synopsis  of  Routine 


PLACE_LOOP  is  an  internal  support  routine  of  the  Enhancements 
Module.  It  outputs  to  the  designate  device  a  string  of  ASCII  characters  repre¬ 
senting  the  value  NUMBER.  The  base  of  the  output  representation  (defined 
range  2  to  16)  and  the  number  of  characters  output  is  selectable.  Blanking  of 
leading  zeros  is  also  selectable. 


PLACE_LOOP  works  its  way  down  from  the  most  significant  place  to 
the  least  significant.  At  each  place,  (base)p,  the  contribution  of  NUMBER  to  the 
mantissa  is  found  and  translated  into  a  character  representing  the  mantissa.  For 
example,  if  the  base  is  16  and  the  contribution  is  11,  the  character  would  be  B. 
NUMBER  is  reduced  by  the  mantissa  contribution  and  PLACE_LOOP  proceeds 
to  the  next  lower  significance  place.  This  process  continues  until  NUMBER  is 
completely  represented. 


5.  Routine  Relationships  Diagram 


Figure  1 2  .  Relationship  of  PLACE_LOOP  to  Other  Routines. 


6.  Invocation 

a.  Invocation  Statement 

PLACE_LOOP  is  invoked  by: 
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PLACE_LOOP(  LOGICAL_UNIT,  BLANKING,  NUMBER,  INDEX,  DIVISOR  ) 

where  LOGICALJJNIT  and  BLANKING  are  of  type  Byte  and  NUMBER,  INDEX, 
and  DIVISOR  are  of  type  Word. 


b.  Parameter  Passing  Schema 

PLACE_LOOP  has  five  input  parameters.  Their  definitions  and  uses 

follow. 


LOGICALJJNIT: 

The  number  of  the  device  to  which  characters  will  be  written. 
Type  Byte. 

BLANKING: 

A  logical  flag  which,  if  true,  indicates  that  leading  zeros  are  to 
be  suppressed.  Type  Byte. 

NUMBER: 

The  value  which  will  be  output.  Type  Word. 

INDEX: 

The  base  value  of  the  most  significant  character  of  the 
output.  For  example,  if  the  output  is  decimal  with  four  digits, 
INDEX  would  be  1 ,000  or  1 04.  INDEX  is  of  type  Word. 

DIVISOR: 

The  base  of  the  output.  Type  Word. 

c.  Routines  Which  Call  PLACE_LOOP 

PLACE_LOOP  is  an  internal  routine  of  the  Enhancements  Module  and 
was  written  to  be  called  only  by  other  Enhancements  Module  routines.  PLACE_ 
LOOP  is  called  by  WRITE_DBYTE,  WRITE  JHBYTE,  WRITE_BBYTE,  WRITE, 
DINTEGER,  WRITE_DWORD,  WRITE_HWORD,  and  WRITE_POINTER. 


7,  variabLss.^ncl  Constants 

a.  Global 

PLACE_LOOP  uses  no  global  variables  or  constants. 


b.  Module 

PLACE_LOOP  uses  no  module  level  variables  or  constants. 

c.  Routine 
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PLACE_LOOP  has  two  routine  level  variables,  VALUE  (type  Word) 
and  CHARACTER  (type  Byte)  in  addition  to  the  input  parameters  NUMBER  and 
INDEX.  The  following  shows  how  the  variables  of  PLACE_LOOP  function  to 
resolve  the  characters  which  represent  NUMBER.  Once  VALUE  is  resolved  it  is 
translated  into  a  CHARACTER  by  routine  ASCII. 


mantissa3  X  base^ 
mantissa2  X  base2 
mantissai  X  base1 
mantissaQ  X  base® 


=  + 


NUMER 


VALUE(3)  X  INDEXp) 
VALUE (2)  X  INDEX(2) 
VALUE(1)XINDEX(1) 
VALUE/0)  X  INDEX/q) 


NUMBER 


where 

VALUE(n)  =  NUMBER^)  /  INDEX(n), 

NUMBER(n_i)  «  NUMBER(n)  MOD  INDEX(n),  and 
INDEX(n_i)  =  INDEX(n)  /  DIVISIOR. 

The  calculation  of  VALUE  and  translation  of  the  VALUES  into  characters  begins 
with  the  most  significant  position  and  proceeds  to  the  least  significant. 


PLACE_LOOP  calls  two  Enhancement  Module  routines  ASCII  and 
PUTCH.  ASCII  is  used  to  translate  the  VALUES  into  CHARACTERS.  ASCII 
receives  VALUE  and  BLANKING  (passed  into  PLACEJLOOP  by  the  calling 
routine)  as  input  parameters  and  returns  to  PLACE_LOOP  BLANKING  and 
CHARACTER.  If  VALUE  is  zero  and  BLANKING  is  true,  CHARACTER  will  be 
returned  as  a  blank  and  BLANKING  as  turn.  Otherwise,  CHARACTER  will  be  the 
ASCII  character  which  represents  VALUE  and  BLANKING  will  be  returned  as 
false. 

PLACE_LOOP  uses  PUTCH  to  output  each  CHARACTER.  PUTCH 
receives  LOGICALJJNIT  (passed  into  PLACE_LOOP  by  the  calling  routine)  and 
CHARACTER.  PUTCH  outputs  the  character  to  the  desired  device.  PUTCH  has 
no  return  parameters. 
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a.  Parameter  Passing  Schema 

PLACE_LOOP  has  no  output  parameters. 

b.  System  Configuration  Changes 

Other  than  the  outputing  of  a  string  of  characters  to  a  device,  PLACE 
LOOP  causes  no  system  configuration  changes. 


10.  Routine  Testing 

a.  Description  of  Test 

PLACE_LOOP  was  not  individually  tested.  Instead  it  was  included  in 
a  test  of  all  the  Enhancement  Module  routines.  As  many  of  the  "write”  and 
"writeln"  routines  depend  upon  PLACE_LOOP,  if  PLACE_LOOP  didn’t  work,  they 
wouldn't  work. 


b.  Results  of  Test 

The  "write"  routines  functioned  properly,  thus  PLACE_LOOP  func¬ 
tioned  properly. 

11.  Reference,  taiistinq 

The  listing  of  PLACE_LOOP  is  on  page  285  in  Appendix  A 
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1.  Routine  Name:  VALID_BINARY_CH 

2.  Internal  routine  of  Ehancements  Module. 

3.  Written  in  PLZ;  four  lines  of  executable  code. 

4.  Svnoosis  of  Routine 

VALID_BINARY_CH  a  simple  internal  support  routine  of  the  Enhancements 
Module.  It  examines  an  input  character  and  determines  whether  it  is  a  "0"  or  a 
"1".  If  it  is,  VALID_BINARY_CH  returns  the  flag  VALIDITY  as  true;  otherwise 
VALIDITY  is  false. 


5.  Routine  Relationships  Diagram 


REA  D_H  BYTE  READ_HWORD 

VALID HEX CH  | 


Figure  13.  Relationship  of  VALID_BINARY_CH  to  Calling  Routines. 


6,  Invocation 

a.  Invocation  Statement 

VALID_BINARY_CH  is  invoked  via: 

VALIDITY  :=  VALID_BINARY_CH(  CHARACTER  ) 
where  both  VALIDITY  and  CHARACTER  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

VALID_BINARY_CH  has  one  input  and  one  output  parameter. 
CHARACTER  is  passed  into  the  routine  and  is  checked  against  "1"  and  "0". 
VALIDITY  is  returned  as  either  true  if  CHARACTER  checks  out.  Otherwise 
VALIDITY  is  returned  as  false. 
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c.  Routines  Which  Call 


VALID_BINARY_CH  is  an  internal  routine  of  Enhancements  Module. 
It  was  written  to  be  called  only  by  other  Enhancements  Module  routines.  As  it 
turns  out,  VALID_  B1NARY_CH  is  not  called  by  any  routines  of  the  Enhancements 
Module.  In  writing  the  other  routines,  an  IF  statement  was  used  to  determine 
whether  the  input  character  was  a  "1"  or  a  "0"  rather  than  calling  VALID_ 
BINARY  CH. 


7.  Variables  and  Constants 

a.  Global 

VALID_BINARY_CH  uses  no  global  constants  or  variables. 


b.  Module  Level 

VALID_BINARY_CH  uses  two  module  constants:  TRUE  -  value  1  hex, 
and  logical  true,  and  FALSE  -  value  0  hex,  logical  false.  VALID_BINARY_CH 
uses  no  module  level  variables. 


c.  Routine 

VALID_BINARY_CH  hs  no  routine  level  constants  or  variables. 

8.  Other  Routines  Called 

VALID_BINARY_CH  calls  no  other  routines 

9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

VALID_BINARY_CH  has  a  single  output  parameter,  VALIDITY,  of  type 
Byte.  It  is  returned  with  the  logical  value  true  if  the  input  CHARACTER  is  either  a 
"1M  or  a  "0".  Otherwise  VALIDITY  is  returned  with  the  logical  value  false. 

b.  System  Configuration  Changes 

VALID_BINARY_CH  causes  no  configuration  changes. 
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VALID_BINARY_CH  was  not  tested  since  it  isn’t  used.  However,  this 
routine  is  vary  similar  to  VALID_DECIMAL_CH  and  VALID_HEX_CH.  These 
routines  performed  properly.  Based  on  their  similarity,  it  is  likely  that 
VALID_BINARY_CH  would  perform  properly. 


VALID_BINARY_CH's  listing  is  on  page  286  in  Appendix  A. 
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1 .  Routine  Name:  VALID_DECIMAL_CH 

2.  Internal  routine  of  Ehancements  Module. 

3.  Written  in  PL Z;  four  lines  of  executable  code. 

4t_Synop£i^QtflQutina 

VALID_DECIMAL_CH  a  simple  internal  support  routine  of  the  En¬ 
hancements  Module.  It  examines  an  input  character  and  determines  whether  it  is 
a  "0"  through  "9".  If  it  is  one  of  these  characters,  VALID_DECIMAL_CH  returns 
the  flag  VALIDITY  as  true;  otherwise  VALIDITY  is  false. 


5.  Routine  Relationships  Diagram 


READ__DI 
READ  DBYTE 
_ ^ _ 

NTEGER 

READ  DWORD 

_ Z _ 

VALID_DECIMAL_CH 

Figure  1 4.  Relationship  of  VALID_DECIMAL_CH  to  Other  Routines 

6,  Invocation 

a.  Invocation  Statement 

VALID_DECIMAL_CH  is  invoked  via: 

VALIDITY  :=  VALID_DECIMAL_CH(  CHARACTER  ) 
where  both  VALIDITY  and  CHARACTER  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

VALID_DECIMAL_CH  has  one  input  and  one  output  parameter. 
CHARACTER  is  passed  into  the  routine  and  is  checked  against  characters  "0" 
through  "9".  VALIDITY  is  returned  as  either  true  if  CHARACTER  checks  out. 
Otherwise  VALIDITY  is  returned  as  false. 
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c.  Routines  Which  Call 

VALID_DECIMAL_CH  is  an  internal  routine  of  Enhancements  Module. 
It  was  written  to  be  called  only  by  other  Enhancements  Module  routines.  VALID_ 
DECIMAL_CH  is  called  by  READ_DBYTE,  READ_DINTEGER,  and  READ_ 
DWORD. 

7.  Variables  and  Constants 

a.  Global 

VALID_DECIMAL_CH  uses  no  global  constants  or  variables. 


b.  Module  Level 

VALID_DECIMAL_CH  uses  two  module  constants:  TRUE  -  value  1 
hex,  logical  true,  and  FALSE  -  value  0  hex,  logical  false. 


c.  Routine 

VALID_DECIMAL_CH  hs  no  routine  level  constants  or  variables. 


t;  8.  Other  Routines  Called 

S  VALID_DECIMAL_CH  calls  no  other  routines. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

VALID_DECIMAL_CH  has  a  single  output  parameter,  VALIDITY,  of 
type  Byte.  It  is  returned  with  the  logical  value  true  if  the  input  CHARACTER  is  a 
"0"  through  "9".  Otherwise  VALIDITY  is  returned  with  the  logical  value  false. 


b.  System  Configuration  Changes 

VALID_DECIMAL_CH  causes  no  configuration  changes. 
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a.  Description  of  Test 

VALID_DECIMAL_CH  was  tested  in  conjunction  with  the  rest  of  the 
Enhancements  Module. 

b.  Results  of  Test 

VALID_DECIMAL_CH  works. 

11.  Reference  to  Listing 

The  listing  for  VALID_DECIMAL_CH  is  on  page  286  in  Appendix  A. 
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1.  Routine  Name:  VALID_HEX_CH 

2.  Internal  routine  of  Ehancements  Module. 

3.  Written  in  PLZ;  four  lines  of  executable  code. 

4.  Synopsis  of  Routine 

VALID_HEX_CH  a  simple  internal  support  routine  of  the  Enhance¬ 
ments  Module.  It  examines  an  input  character  and  determines  whether  it  is  a  "0" 
through  "9"  or  "A"  through  "F"  (note  upper  case  only).  If  it  is  one  of  these  chara¬ 
cters,  VALID_HEX_CH  returns  the  flag  VALIDITY  as  true;  otherwise  VALIDITY  is 
false. 

5.  Routine  Relationships  Diagram 


READ  HBYTE 

READ  HWORD 

.  X 

I  VALID 

HEX  CH  1 

1 _  ~ 

: _ _= _ 1 

_ 

Figure  1 5.  Relationship  of  VALID_HEX_CH  to  Other  Routines. 

6.  Invocation 

a.  Invocation  Statement 

VALID_HEX_CH  is  invoked  via: 

VALIDITY  :=  VALID_HEX_CH(  CHARACTER  ) 
where  both  VALIDITY  and  CHARACTER  are  of  type  Byte. 

b.  Parameter  Passing  Schema 

VALID_HEX_CH  has  one  input  and  one  output  parameter.  CHARA¬ 
CTER  is  passed  into  the  routine  and  is  checked  against  characters  "0"  through 
"9"  and  "A"  though  "F".  VALIDITY  is  returned  as  either  true  if  CHARACTER 
checks  out.  Otherwise  VALIDITY  is  returned  as  false. 
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c.  Routines  Which  Call 

VALID_HEX_CH  is  an  internal  routine  of  Enhancements  Module.  It 
was  written  to  be  called  only  by  other  Enhancements  Module  routines.  VALID_ 
HEX_CH  is  called  by  READJHBYTE  and  READ_HWORD. 

7:  Variables  and  Constants 

a.  Global 

VALID_HEX_CH  uses  no  global  constants  or  variables. 

b.  Module  Level 

VALID_HEX_CH  uses  two  module  constants:  TRUE  -  value  1  hex, 
logical  true;  FALSE  -  value  0  hex,  logical  false. 

c.  Routine 

VALID_HEX_CH  hs  no  routine  level  constants  or  variables. 

8.  Other  Routines  Called 

VALID_HEX_CH  calls  no  other  routines 

9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

VALID_HEX_CH  has  a  single  output  parameter,  VALIDITY,  of  type 
Byte.  It  is  returned  with  the  logical  value  true  if  the  input  CHARACTER  is  a  "0" 
through  "9"  or  "A"  through  "F" .  Otherwise  VALIDITY  is  returned  with  the  logical 
value  false. 

b.  System  Configuration  Changes 

VALID_HEX_CH  causes  no  configuration  changes. 
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a.  Description  of  Test 

VALID_HEX_CH  was  tested  in  conjunction  with  the  rest  of  the  En 
hancements  Module  rather  than  being  individually  tested. 

b.  Results  of  Test 

VALID_HEX_CH  works. 

11.  Reference  to  Listing 

The  listing  of  VAL1D_HEX_CH  is  on  page  287  in  Appendix  A. 
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a.  Invocation  Statement 


WRITE  and  WRITELN  are  invoked  with: 

WRITE(  LOGICAL_UNlT,  BUFFER_PTR)  and 
WRUELN(  LOGICAL_UNIT,  BUFFER_PTR) 
where  LOGICAL_UNIT  is  type  Byte  and  BUFFER_PTR  is  of  type  Pointer-to-Byte. 


b.  Input  Parameter  Passing  Schema 

Both  WRITE  and  WRITELN  have  two  input  parameters,  LOGICAL. 
UNIT  and  BUFFER.PTR.  LOGICAL_UNIT  brings  in  the  number  of  the  device  the 
output  is  to  go  to.  BUFFER_PTR  points  to  the  memory  location  where  the  first 
character  of  string  to  be  output  is  located. 


c.  Routines  Which  Call 

As  global  routines  of  the  Ehancements  module,  WRITE  &  WRITELN 
can  be  called  by  any  PLZ  routine  which  is  linked  in  with  Enhancements  module. 
In  addition  to  this  purpose,  WRITE  is  used  by  some  other  routines  in  Enhance¬ 
ments  Module.  Specifically,  WRITE  is  called  by  WRITE_LBYTE  and  WRITE. 
RCODE. 


7.  Variables  and  Constants 
a.  Global 

Neither  WRITE  nor  WRITELN  use  any  global  variables  or  constants. 


b.  Module 

Neither  routine  uses  any  module  level  variables.  WRITE  uses  the 
Enhancements  Module  constant  CARRIAGE  RETURN. 
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c.  Routine 

WRITE  uses  three  routine  level  variables,  LENGTH  (type  Word), 
RETURN_CODE  (type  Byte),  and  PINDEX  (type  Pointer-To-Byte).  LENGTH  is 
used  to  pass  the  length  of  the  output  character  string  to  the  external  routine 
PUTSEQ.  RETURN_CODE  receives  the  system  completion  code  sent  back  from 
PUTSEQ.  PINDEX  is  a  place  keeper  pointer  for  the  string  to  be  output.  WRITELN 
uses  no  module  level  variables.  Neither  routine  uses  any  routine  level  constants. 


8.  Other  Routines  Called 

In  addition  to  WRITELN's  calling  of  WRITE,  WRITE  calls  the  external 
routine  PUTSEQ  to  output  strings  characters  and  WRITELN  calls  PUTCH  to  out¬ 
put  the  carriage  return. 

a.  PUTSEQ 

This  PLZ  STREAM.  10  Module  routine  is  declaired  external  to  the 
Enhancements  Module.  WRITE  uses  PUTSEQ  to  output  the  string  of  characters 
to  the  desinated  device  driver.  PUTSEQ  has  three  input  parameters,  LOGICAL_ 
UNIT  (type  Byte),  BUFFER_PTR  (type  Pointer-to-Byte),  and  LENGTH  (type  Word), 
and  has  two  return  parameters,  LENGTH  (type  Word)  and  RETURN_CODE  (type 
Byte).  LOGICALJJNIT  is  the  same  as  the  input  parameter  to  WRITE  and 
WRITELN,  the  number  of  the  device  driver  to  which  the  output  will  be  directed. 
BUFFER_PTR  points  to  the  first  character  of  the  string  to  be  output.  LENGTH  is 
the  number  of  characters  (Bytes)  to  be  output.  The  return  parameter  LENGTH 
carries  the  number  of  characters  which  were  output  by  PUTSEQ.  RETURN_ 
CODE  returns  the  operating  system  completion  code  or  error  code  for  the  output 
operation.  PUTSEQ  is  invoked  via: 

LENGTH,  RETURN_CODE  := 

PUTSEQ(  LOGICALJJNIT,  BUFFER_PTR,  LENGTH  ). 


b.  PUTCH 

PUTCH  is  an  internal  support  routine  of  the  Enhancements  Module.  It 
has  two  input  parameters,  LOGICALJJNIT  and  CHARACTER,  both  of  type  Byte. 
LOGICAL_  UNIT  holds  the  number  of  the  device  driver  to  which  the  character  is 
to  be  output.  CHARACTER  passes  the  character  to  be  output.  PUTCH  is  invoked 
with: 


PUTCH(  LOGICALJJNIT,  CHARACTER ). 
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From  WRITELN,  CHARACTER  passes  "%R",  the  RIO  constant  for  a  carriage  re¬ 
turn.  PUTCH  has  no  return  parameters. 


9.  Output  of  Routine 

Neither  WRITE  or  WRITELN  have  output  parameters.  Nor  does  either 
routine  affect  the  system  configuration  beyond  writing  characters  to  some  logical 
unit. 


10.  Routine  Testing 

a.  Description  of  Test 

WRITE  and  WRITELN  were  tested  along  with  the  rest  of  the  Enhance¬ 
ments  module  routines.  A  module  of  test  routines  called  TESTJT  was  used  to 
out-  put  strings  to  the  system  console  via  WRITE  and  WRITELN. 

b.  Results  of  Test 

WRITE  and  WRITELN  performed  property. 

11.  Reference  to  Listing 

The  listing  of  WRITE  and  WRITELN  are  on  page  288  in  Appendix  A. 
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1 .  Routine  Names: 

WRITE_DBYTE,  WRITE_HBYTE,  WRITE_BBYTE, 
WRITELN_DBYTE,  WRITELN_HBYTE,  and  WRITELN_BBYTE 


2.  Output  routines  of  Enhancements  Module. 


3.  Written  in  PLZ. 

WRITE_DBYTE:  five  lines  of  executable  code. 
WRITE_HBYTE:  five  lines  of  executable  code. 
WRITE_BBYTE:  five  lines  of  executable  code. 
WRITELN_DBYTE :  three  lines  of  executable  code. 
WRITELN_HBYTE:  three  lines  of  executable  code. 
WRITELN  BBYTE:  three  lines  of  executable  code. 


4.  Synopsis  of  Routines 

These  six  routines  take  a  single  byte  value  and  output  the  ASCII 
characters  which  represent  it.  The  DBYTE  routines  output  the  value  in  base  10 
as  a  decimal  value,  one  to  three  characters  (0  through  9  or  space)  followed  by  a 
decimal  point.  The  DBYTE  routines  blank  leading  zeros  in  the  100's  and  10's 
places.  The  HBYTE  routines  output  the  value  in  hexidecimal  form,  two  characters 
(0  to  9  and  A  to  F)  followed  by  an  H.  The  BBYTE  routines  output  a  binary  repre¬ 
sentation  of  the  value,  eight  chararcters  (0  &  1 )  followed  by  a  B.  The  WRITE  form 
of  the  routines  does  not  output  a  carriage  return  at  the  end  of  the  string:  the 
WRITELN  forms  do.  It  is  up  to  the  calling  routine  to  put  CHARACTER  in  the 
proper  form  prior  to  calling  any  of  the  WRITE  or  WRITELN  routines.  For  example, 
a  number  stored  in  complements  form  would  have  to  be  transformed  before 
WRITE_DBYTE  was  called.  The  WRITELN  forms  function  by  calling  the  WRITE 
version  to  output  the  character  strings  and  then  call  another  routine  to  output  the 
carriage  return. 

All  three  WRITE  routines  function  identically:  the  only  difference  be¬ 
tween  them  is  the  values  assigned  to  the  internal  variables  BLANKING  and 
INDEX  and  the  output  base  value  (10,  16,  or  2)  passed  to  routine  PLACE_ 
LOOP.  PLACE_LOOP  performs  the  actual  conversion  of  the  byte  value  into  the 
character  string  given  the  base  desired  and  the  order  or  INDEX  of  the  most 
significant  output  character.  The  values  for  the  three  routines  are: 
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WRITE_DBYTE 
WRITE_HBYTE 
WRITE  BBYTE 


Any  PLZ  Routine 


DBYTE 

WRITELN  -MBYTE 

BBYTE 


_  _DBYTE 

WRITE  -MBYTE 

BBYTE 


PLACE  LOOP 


PUTCH 


Figure  1 7.  Relationship  of  Byte  WRITE_xBYTE  and 
WRITELN  xBYTE  Routines  to  Other  Routines 


a.  Invocation  Statement 

The  routines  are  invoked  from  calling  PLZ  routines  via: 

WRITE_DBYTE(  LOGICALJJNIT,  NUMBER ) 
WRITELN_DBYTE(  LOGICALJJNIT,  NUMBER ) 
WRITE_HBYTE(  LOGICAL_UNIT,  NUMBER ) 
WRITELN  JHBYTE(  LOGICAL_UNIT,  NUMBER ) 
WRITE_BBYTE(  LOGICAL_UNIT,  NUMBER ) 
WRITELN  J3BYTE(  LOGICAL_UNIT,  NUMBER  ) 

where  LOGICAL_UNIT  and  NUMBER  are  of  type  Byte. 

b.  Parameter  Passing  Schema 


Enhancements  Module 


All  six  routines  have  the  same  two  input  parameters,  LOGICAL_UNIT 
and  NUMBER,  both  of  type  Byte.  LOGICALJJNIT  is  the  number  of  the  device  the 
characters  are  to  be  output  to.  NUMBER  is  the  value  to  be  translated  into  deci¬ 
mal,  hexidecimal,  or  binary  character  representations. 


c.  Routines  Which  Call 

These  six  routines  can  be  called  by  any  PLZ  program.  The  Enhance¬ 
ments  Module  and  the  PLZ  Stream.  10  Module  must  be  linked  in  with  the  calling 
programs'  module. 


None  of  the  routines  use  any  global  variables  or  constants  aside  from 
the  definitions  of  ASCII  characters. 


b.  Module 

None  of  the  routines  use  any  module  level  variables;  The  WRITE  form 
routines  use  no  module  level  constants.  The  WRITELN  forms  use  the  PLZ  con¬ 
stant  %R  to  represent  a  carrage  return. 


c.  Routine 

The  WRITELN  form  routines  use  no  routine  level  constants  or  vari¬ 
ables.  The  WRITE  forms  use  two  variables,  BLANKING  of  type  Byte  and  INDEX 
of  type  Word.  BLANKING  is  used  as  a  logical  flag  to  indicate  to  routine  PLACE_ 
LOOP  whether  leading  zeros  are  to  be  blanked.  INDEX  is  used  to  pass  the  value 
of  the  most  significant  place  of  the  output  string  to  routine  PLACE_LOOP.  Neither 
of  these  variables  are  necessary,  they  are  present  solely  to  aid  the  readability  of 
the  routines. 


The  WRITE  and  WRITELN  routines  call  two  internal  routines  of  the  En¬ 
hancements  Module,  PUTCH  and  PLACE_LOOP. 
a.  PUTCH 
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All  six  routines  call  PUTCH  to  output  single  characters  to  the  desired 
logical  unit.  WRITE_DBYTE  outputs  a  decimal  point,  WR1TE_HBYTE  outputs  an 
H,  WRITE_  BBYTE  outputs  a  B,  and  the  WRITELN's  output  a  carriage  return.  In 
all  cases  PUTCH  is  invoked  via: 

PUTCH(  LOGICAL_UNIT,  CHARACTER ) 

where  both  LOGICALJJNIT  and  CHARACTER  are  of  type  Byte.  LOGICALJJNIT 
is  the  same  as  the  input  parameter  to  the  WRITE  and  WRITELN  routines,  the 
number  of  the  device  to  which  the  CHARACTER  is  to  be  written.  CHARACTER  is 
the  hex  value  of  the  ASCII  character  to  be  output.  PUTCH  does  not  check  to  see 
if  the  CHARACTER  is  valid  ASCII.  As  the  WRITE  and  WRITELN  routines  use 
PUTCH  to  output  constants  no  error  checking  is  needed.  PUTCH  has  no  return 
parameters. 


b.  PLACE_LOOP 

PLACE_LOOP  is  called  by  the  three  WRITE  form  routines  to  translate 
a  value  into  a  string  of  characters  which  represent  that  value  and  to  output  those 
characters  to  a  designated  device.  PLACEJ-OOP  is  invoked  in  the  three  Write 
routines  with: 

PLACE_LOOP(  LOGICALJJNIT,  BLANKING, 

WORD(  NUMBER  ),  INDEX,  BASE  ) 

where  INDEX  is  of  type  Word,  NUMBER  is  of  type  Byte  converted  to  type  Word, 
and  the  other  three  input  parameters  are  of  type  Byte.  LOGICALJJNIT  is  the 
same  as  the  input  parameter  to  the  WRITE  and  WRITELN  routines,  the  number  of 
the  device  to  which  the  string  of  characters  is  to  be  written.  BLANKING  is  a  logi¬ 
cal  flag  indicating  whether  leading  zeros  are  to  be  blanked.  NUMBER  is  the 
value  to  be  translated  into  a  string  of  characters.  Note  that  the  input  parameter  to 
the  WRITE  and  WRITELN -routines  NUMBER  is  of  type  Byte  and  the  input  to 
PLACEJ-OOP  is  of  type  Word.  Thus  the  type  conversion  in  the  invocation  of 
PLACE_LOOP.  INDEX  is  the  value  of  the  most  significant  character  to  be  output. 
BASE  is  the  base  in  which  the  character  representation  is  to  be  made.  PLACE_ 
LOOP  has  no  output  parameters. 

PLACEJ-OOP  does  no  range  checking  on  its  inputs.  This  is  not  a 
problem  as  the  WRITE  routines  pass  BLANKING,  INDEX,  and  BASE  as  con¬ 
stants.  With  the  constants  passed  and  the  input  NUMBER  limited  to  a  single  byte 
range,  the  inputs  to  PLACEJ-OOP  cannot  be  out  side  defined  ranges.  It  is 
assumed  that  the  correct  LOGICALJJNIT  number  is  passed  into  the  WRITE  and 
WRITELN  routines. 
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The  six  routines  have  no  output  parameters.  The  only  effect  they  have  on 
the  configuration  of  the  system  is  the  writing  of  a  number  characters  (two  to  ten)  to 
some  logical  unit. 


10.  Routine  Testing 

a.  Description  of  Test 

These  six  routines  were  tested  in  conjunction  with  the  rest  of  the  En¬ 
hancements  module  routines.  Each  routine  was  given  a  number  of  values  to 
output. 


b.  Results  of  Test 

Each  routine  output  its  test  values  in  the  proper  formats. 


iit  Reference  to  Listing 

The  listings  for  these  routines  are  found  on  the  following  pages. 


_ Bawling _ 

WRITE_DBYTE 

WRITELN_DBYTE 

WRITE_HBYTE 

WRITELN_HBYTE 

WRITE_BBYTE 

WRITELN  BBYTE 


Page 

289  in  Appendix  A 

289  in  Appendix  A 

290  in  Appendix  A 

290  in  Appendix  A 

291  in  Appendix  A 
291  in  Appendix  A 
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1 .  Routine  Name:  WRITE_LBYTE  and  WRITELN _LBYTE 

2.  Output  routines  of  Enhancements  Module. 

3.  Written  in  PL Z. 

WRITE_LBYTE:  six  lines  of  executable  code. 

WRITELN  LBYTE:  three  lines  of  executable  code. 


These  two  routines  take  a  single  byte  defined  as  a  logical  value  and 
output  the  text  string  equivalent  of  the  byte's  value.  Three  string  outputs  are  pos¬ 
sible.  If  the  value  of  the  byte  is  uniary,  "TRUE  "  is  output.  If  the  value  is  zero, 
"FALSE"  is  output.  If  the  byte  has  any  other  value,  the  output  is  "UNDF  ".  Note 
that  all  three  output  strings  are  five  characters  long.  The  difference  between 
WRITE_LBYTE  and  WRITELN_BYTE  is  the  same  as  in  Pascal;  WRITE_LBYTE 
does  not  output  a  carriage  return  and  WRITELN_  LBYTE  does.  WRITELN_ 
LBYTE  calls  WRITE_LBYTE  to  perform  the  five  character  string  output  and  then 
calls  PUTCH  to  output  the  cartage  return. 


Any  PL Z  Routine 


WRITELN  LBYTE 


WRITE  LBYTE 


WRITE 


PUTCH 


Figure  18.  Relationship  of  Logical-Byte  Wnte  and  Writeln 
Routines  to  Other  Routines 
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a.  Invocation  Statement 
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The  routines  are  invoked  from  a  calling  PLZ  routine  by: 

WRITE_LBYTE{  LOGICAL_UNIT,  FLAG ) 
WRITELN_LBYTE(  LOGICALJJNIT,  FLAG) 

where  LOGICALJJNIT  and  FLAG  are  both  of  type  Byte. 


b.  Parameter  Passing  Schema 

Both  routines  have  two  input  parameters,  LOGICAL_UNIT  and  FLAG. 
LOGICALJJNIT  is  the  number  of  the  device  the  character  string  is  to  be  written  to. 
FLAG  holds  the  logical  variable  to  be  translated  into  text. 

c.  Routines  Which  Call 

Both  routines  can  be  used  by  any  PLZ  language  program  with  which 
the  Enhancements  Module  and  the  PLZ  Stream.lO  Module  have  been  linked. 
The  routines,  like  the  rest  of  the  global  Enhancements  module  routines,  are 
Pascal-like  IO  subroutines  intended  to  reduce  the  difficulty  of  10  in  PLZ. 


7.  -Variables  and  Constants 

a.  Global 

No  global  variables  are  used  by  either  routine.  Both  routines  require 
logical  true  to  be  defined  as  01  hex  and  logical  false  to  be  defined  as  00  hex. 
Both  routines  also  follow  the  PLZ  convention  of  "%R"  representing  a  carriage 
return. 


b.  Module 

Neither  routine  uses  any  module  level  variables.  Within  the  Enhance¬ 
ments  Module,  TRUE  is  a  constant  of  value  01  hex  representing  logical  true  and 
FALSE  is  a  constant  of  value  00  hex  representing  logical  false. 
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c.  Routine 


Routine  level  variables  and  constants  are  not  used  by  either  routine. 


8.  Other  Routines  Called 

Both  WRITE_LBYTE  and  WRITELN_LBYTE  use  other  Enhancements 
Module  routines  to  output  characters.  WRITE_LBYTE  uses  the  global  routine 
WRITE  and  WRITELN_LBYTE  uses  the  internal  routine  PUTCH. 

a.  WRITE 

WRITE  is  very  similar  to  its  Pascal  namesake.  It  outputs  a  designated 
string  of  characters.  WRITE_LBYTE  uses  WRITE  to  output  "TRUE ",  "FALSE",  or 
"UNDF "  to  the  designated  logical  unit.  WRITE  has  two  input  parameters 
LOGICALJJNIT,  ot  type  Byte,  and  TEXT_POINTER,  of  type  pointer-to-byte  or 
Pbyte.  WRITE’S  L0GICAL_UN1T  services  the  same  function  as  WRITE J-BYTE's 
input  parameter  LOGICALJJNIT.  It  is  the  name  of  the  device  to  which  the  chara¬ 
cters  will  be  written.  TEXT_POINTER  is  a  pointer  (two  bytes)  to  a  specific  memory 
location,  the  location  of  the  string  to  be  output.  For  WRITE_  LBYTE,  the  string  is 
entered  as  a  constant  in  the  invocations  of  WRITE.  PLZ  translates  this  into  a 
pointer  to  the  first  character  of  the  string.  The  "%R"  (carriage  return)  is  used  by 
PLZ  to  denote  end-of-string.  Thus  the  invocation  of  WRITE  from  WRITE_LBYTE 
looks  like  the  following. 

WRITE  ( LOGICALJJNIT,  'string  to  be  output%R' ) 

WRITE  has  no  return  parameters. 


b.  PUTCH 

WRITELN_LBYTE  uses  PUTCH  to  output  a  carriage_return  to  the 
designated  logical  unit.  PUTCH  has  two  input  parameters,  LOGICALJJNIT  and 
CHARACTER.  As  with  WRITE,  LOGICALJJNIT  is  the  Byte  parameter  indicating 
which  device  the  output  is  to  go  to.  CHARACTER,  also  of  type  Byte,  holds  the 
ASCII  character  to  be  output.  For  WRITELN  JBYTE,  PUTCH  is  invoked  by: 

PUTCH(  LOGICALJJNIT,  '%R' ) 

where  '%R'  denotes  a  carriage_return.  PUTCH  has  no  return  parameters. 


9.  Outom  of  Routine 
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Neither  routine  has  any  output  parameters.  The  sole  effect  of  the 
routines  upon  the  system  is  the  writing  of  five  characters  and,  if  WRITELN_ 
LBYTE,  a  carriage  return  to  the  designated  logical  unit. 


10.  Routine  Testing 

a.  Description  of  Test 

WRITE J-BYTE  AND  WRITELNJ.BYTE  were  tested  along  with  the  rest 
of  Enhancements  Module.  This  test  was  accomplished  by  linking  with  Enhance¬ 
ments  Module  and  the  PLZ  STREAM.  10  Module  with  a  module  of  test  routines. 


b.  Results  of  Test 

WRITE_LBYTE  and  WRITE_LBYTE  output  the  correct  text  strings  to 
the  correct  logical  units. 


11.  Reference  to  Listing 

The  listings  of  WRJTE_LBYTE  and  WRJTELN_LBYTE  are  on  page  292 
in  Appendix  A. 
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1.  Routine  Names:  WRITE_DINTEGER  and  WRITELN_DINTEGER 

2.  Output  routines  of  Enhancements  Module. 

3.  Written  in  PLZ.  WRITE_D1NTEGER:  1 1  lines  of  executable  code. 

WRITELN  DINTEGER:  3  lines  of  executable  code. 


WRITE_DINTEGER  and  WRITELN_DINTEGER  take  a  PLZ  Integer 
type  value,  translate  it  into  the  ASCII  characters  that  represent  the  base  10  mag¬ 
nitude  of  the  value,  and  then  output  the  characters  to  a  specified  logical  unit. 
Since  Integer  type  values  have  sign,  WRITE_DINTEGER  and  WRITELN_ 
DINTEGER  put  a  blank  or  a ahead  of  the  character  string  to  indicate  the  sign  of 
the  value.  After  the  last  character,  the  routines  output  a  decimal  point.  Then, 
WRITELN_DINTEGER  only  outputs  a  carriage_return.  Both  routines  blank  lead¬ 
ing  zeros. 

WRITE_DINTEGER  does  most  of  the  work  for  both  routines  as 
WRITELN_DINTEGER's  first  statement  is  a  call  of  WRITEJDINTEGER.  WRITE_ 
DINTEGER  first  determines  the  sign  of  the  value  and  outputs  a  blank  for  positive 
or  a  for  negative  via  routine  PUTCH.  If  the  value  was  negative,  it  is  converted 
to  a  positive  value,  the  sign  already  output.  WRITEJDINTEGER  then  calls 
PLACEJ.OOP  to  perform  the  actual  translation  of  value  to  characters.  WRITE_ 
DINTEGER  ends  by  outputting  a  decimal  point  via  PUTCH.  WRITELN_ 
DINTEGER  ends  by  outputting  a  carriage  return. 


3 


a.  Invocation  Statement 


The  routines  are  invoked  from  calling  PLZ  programs  via: 

WRITE_DINTEGER(  LOGICALJJNIT,  INJNTEGER ) 
WRITELN_DINTEGER(  LOGICAL_UNIT,  INJNTEGER ) 

where  LOGICAL_UNIT  is  type  Byte  and  INJNTEGER  is  type  Integer. 


b.  Parameter  Passing  Schema 

Both  routines  have  two  input  parameters,  LOGICALJJNIT  and  IN_ 
INTEGER.  LOGICALJJNIT  is  the  number  of  the  device  the  output  characters  are 
to  go  to.  INJNTEGER  is  the  value  to  be  output  in  character  form. 


c.  Routines  Which  Call 

WRITE_DINTEGER  and  WRITELN_DINTEGER  can  be  called  by  any 
PLZ  program  that  has  been  linked  with  the  Enhancements  and  PLZ  STREAM.  10 
modules. 


a.  Global 

Neither  routine  uses  any  global  variables.  WRITE_DINTEGER  uses 
no  global  constants.  WRITELN_DINTEGER  follows  the  PLZ  convention  of  %R 
representing  a  carriage  return. 


b.  Module 

Neither  routine  uses  any  module  level  variables  and  WRITELN_ 
DINTEGER  uses  no  module  level  constants.  WRITEJDINTEGER  uses  the 
Enhancements  Module  constant  TRUE  which  represents  logical  true. 


c.  Routine 

WRITELN  DINTEGER  uses  no  routine  level  variables  or  constants. 
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WRITE_  DINTEGER  does  have  three  variables,  BLANKING  (type  Byte),  INDEX 
(tyne  Word),  and  NUMBER  (type  Word).  BLANKING  is  a  logical  flag  to  routine 
PLACE_  LOOP  to  indicate  whether  leading  zeros  are  to  be  blanked.  It  is  set  to 
TRUE.  INDEX  passes  the  place  value  of  the  most  significant  character  of  the  out¬ 
put  string  to  PLACE_  LOOP;  INDEX  is  set  to  10000  decimal.  Neither  of  these 
variable  are  necessary  though,  constants  could  have  been  used.  These  vari¬ 
ables  are  present  only  to  aid  routine  documentation.  NUMBER  on  the  other 
hand,  is  used  to  pass  the  input  Integer  value  to  PLACE_LOOP  which  uses  a 
Word  type  input. 


WRITE_DINTEGER  and  WRITELN_DINTEGER  call  two  internal 
routines  of  the  Enhnancements  module,  PUTCH  and  PLACE_LOOP. 

a.  PUTCH 

Both  routines  call  PUTCH  to  output  single  characters.  WRITE_ 
DINTEGER  uses  PUTCH  to  output  the  sign  of  the  value,  a  blank  or  a  and  to 
output  the  decimal  point.  WRITELN_DINTEGER  uses  PUTCH  to  putput  its 
carriage  return.  PUTCH  is  invoked  via: 

PUTCH(  LOGICAL_UNIT,  CHARACTER ) 

where  both  input  parameter  are  type  Byte.  LOGICALJJNIT  is  the  same  as  the 
input  parameter  parameter  LOGICALJJNIT  for  WRITE_DINTEGER  and 
WRITELN_DINTEGER.  CHARACTER  holds  the  ASCII  character  to  be  output. 
PUTCH  has  no  return  parameters. 


b.  PLACE_LOOP 

PLACEJLOOP  translates  an  input  value  into  the  characters  that 
represent  that  value.  PLACE_LOOP  is  called  by: 

PLACE_LOOP(  LOGICALJJNIT,  BLANKING,  NUMBER,  INDEX,  BASE  ) 

where  INDEX  and  NUMBER  are  type  WORD  and  LOGICALJJNIT,  BLANKING, 
and  BASE  are  type  Byte.  LOGICALJJNIT  is  the  device  number  for  output. 
BLANKING  is  a  logical  flag  indicating  whether  leading  zeros  are  to  be  blanked. 
NUMBER  is  the  value  to  be  converted  to  text  representation.  INDEX  is  the  place- 
value  of  the  most  significant  character  to  be  output.  BASE  is  the  base  the  output 
string  is  to  be  in.  PLACE_LOOP  has  no  return  parameters. 
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WRITE_DINTEGER  and  WRITELN_DINTEGER  have  no  output 
parameter  and  only  effect  the  system  by  outputing  seven  characters,  and  a 
carriage  return  if  WRITELN_  DINTEGER,  to  some  logical  unit. 


10.  Routine  Testing 

a.  Description  of  Test 

WRITE_DINTEGER  and  WRITELN_DINTEGER  were  tested  along  with 
the  other  Enhancements  Module  routines  though  the  module  TESTJT.  TESTJT 
routines  exercised  WRITE  DINTEGER  and  WRITELN  DINTEGER. 


b.  Results  of  Test 

Both  routines  performed  properly. 


11.  Reference  to  Listing 

The  program  listings  for  WRITE_DINTEGER  and  WRITELN 
DINTEGER  can  be  found  on  pages  293  in  Appendix  A. 
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1.  Routine  Names: 

WRITE_DWORD,  WRITE_HWORD, 
WRITELN_DWORD,  and  WRITELN_HWORD 


2.  Output  routines  of  Enhancements  Module. 


3.  Written  in  PL Z. 


WRITE_DWORD:  five  lines  of  executable  code. 
WRITE_HWORD:  five  lines  of  executable  code. 
WRITELN_DWORD:  three  lines  of  executable  code. 
WRITELN  HWORD:  three  lines  of  executable  code. 


These  four  routines  take  a  Word  value  and  output  the  ASCII  chara¬ 
cters  which  represent  it.  The  DWORD  routines  output  the  value  in  base  10  as  a 
decimal  value,  one  to  five  characters  (0  through  9  or  space)  followed  by  a  deci¬ 
mal  point.  The  DWORD  routines  blank  leading  zeros  in  the  10,000s,  1,000s, 
100s,  and  10s  places.  The  HWORD  routines  output  the  value  in  hexidecimal 
form,  four  characters  (0  to  9  and  A  to  F)  followed  by  an  H.  The  WRITE  form  of 
the  routines  does  not  output  a  carriage  return  at  the  end  of  the  string;  the 
WRITELN  forms  do.  The  WRITELN  forms  function  by  calling  the  WRITE  version 
to  output  the  character  strings  and  then  call  PUTCH  to  output  the  carriage  return. 


Both  WRITE  routines  function  identically;  the  only  difference  between 
them  is  the  values  assigned  to  the  internal  variables  BLANKING  and  INDEX  and 
the  output  base  value  (10  or  16)  passed  to  routine  PLACE_LOOP.  PLACE_ 
LOOP  performs  the  actual  conversion  of  the  WORD  value  into  the  character  string 
given  the  base  desired  and  the  order  or  INDEX  of  the  most  significant  output 
character.  The  values  for  the  routines  are: 


WRITE  DWORD 


TRUE 


1 0,000 


WRITE  HWORD 


FALSE 


4,096 
(1000  hex) 
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Any  PLZ  Routine 


Figure  20.  Relationship  of  Decimal  and  Hexidecimal  Word 
Write  and  Writeln  Routines  to  Other  Routines. 


a.  Invocation  Statement 

The  routines  are  invoked  from  calling  PLZ  routines  via: 

WRITE_DWORD(  LOGICALJJNIT,  NUMBER ) 
WRITELN_DWORD(  LOGICAL_UNIT,  NUMBER ) 
WRITE_HWORD(  LOGICALJJNIT,  NUMBER ) 
WRITELN_HWORD(  LOGICAL_UNIT,  NUMBER ) 

where  LOGICALJJNIT  is  type  Byte  and  NUMBER  is  type  Word. 


b.  Parameter  Passing  Schema 

All  four  routines  have  the  same  two  input  parameters,  LOGICAL_ 
UNIT,  type  Byte,  and  NUMBER,  type  Word.  LOGICALJJNIT  is  the  number  of  the 
device  the  characters  are  to  be  output  to.  NUMBER  is  the  value  to  be  translated 
into  decimal  or  hexidecimal  character  representations. 
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c.  Routines  Which  Call 


These  routines  can  be  called  by  any  PL Z  program.  The  Enhance¬ 
ments  Module  and  the  PLZ  Stream.lO  Module  must  be  linked  in  with  the  calling 
programs'  module. 


7.  Variables  and  Constants 

a.  Global 

None  of  the  routines  use  any  global  variables  or  constants  aside  from 
the  definitions  of  ASCII  characters. 


b.  Module 

None  of  the  routines  use  any  module  level  variables;  The  WRITE  form 
routines  use  no  module  level  constants.  The  WRITELN  forms  use  the  PLZ  con¬ 
stant  %R  to  represent  a  carrage  return. 


c.  Routine 

The  WRITELN  form  routines  use  no  routine  level  constants  or  vari¬ 
ables.  The  WRITE  forms  use  two  variables,  BLANKING  of  type  WORD  and 
INDEX  of  type  Word.  BLANKING  is  used  as  a  logical  flag  to  indicate  to  routine 
PLACE_LOOP  whether  leading  zeros  are  to  be  blanked.  INDEX  is  used  to  pass 
the  value  of  the  most  significant  place  of  the  output  string  to  routine  PLACE_ 
LOOP.  These  variables  could  have  been  constants;  they  are  present  solely  to  aid 
the  readability  of  the  routines. 


8.  Other  Routines  Called 

The  WRITE  and  WRITELN  routines  call  two  internal  routines  of  the 
Enhancements  Module,  PUTCH  and  PLACE_LOOP. 

a.  PUTCH 

All  four  routines  call  PUTCH  to  output  single  characters  to  the  desired 
logical  unit.  WRITE_DWORD  outputs  a  decimal  point,  WRITE_HWORD  outputs 
an  H,  and  the  WRITELN's  output  a  carriage  return.  In  all  cases  PUTCH  is  in¬ 
voked  via; 
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v •'•  PUTCH(  LOGICAL_UNIT,  CHARACTER  ) 

where  both  LOGICALJJNIT  and  CHARACTER  are  type  Byte.  LOGICAL_UNIT  is 
the  same  as  the  input  parameter  to  the  WRITE  and  WRITELN  routines,  the  num¬ 
ber  of  the  device  to  which  the  CHARACTER  is  to  be  written.  CHARACTER  is  the 
hex  value  of  the  ASCII  character  to  be  output.  PUTCH  does  not  check  to  see  if 
the  CHARACTER  is  valid  ASCII.  As  the  WRITE  and  WRITELN  routines  use 
PUTCH  to  output  constants  no  error  checking  is  needed.  PUTCH  has  no  return 
parameters. 


b.  PLACE_LOOP 

PLACE_LOOP  is  called  by  the  WRITE  form  routines  to  translate  a 
value  into  a  string  of  characters  which  represent  that  value  and  to  output  those 
characters  to  a  designated  device.  PLACE_LOOP  is  invoked  by: 

PLACE_LOOP(  LOGICALJJNIT,  BLANKING,  NUMBER  ,  INDEX,  BASE) 

where  INDEX  is  of  type  Word,  NUMBER  is  of  type  WORD  converted  to  type  Word, 
and  the  other  three  input  parameters  are  of  type  WORD.  LOGICALJJNIT  is  the 
same  as  the  input  parameter  to  the  WRITE  and  WRITELN  routines,  the  number  of 
the  device  to  which  the  string  of  characters  is  to  be  written.  BLANKING  is  a  logi¬ 
cal  flag  indicating  whether  leading  zeros  are  to  be  blanked.  NUMBER  is  the 
value  to  be  translated  into  a  string  of  characters.  Note  that  the  input  parameter  to 
the  WRITE  and  WRITELN  routines  NUMBER  is  of  type  WORD  and  the  input  to 
PLACEJ.OOP  is  of  type  Word.  Thus  the  type  conversion  in  the  invocation  of 
PLACEJ.OOP.  INDEX  is  the  value  of  the  most  significant  character  to  be  out¬ 
put.  BASE  is  the  base  in  which  the  character  representation  is  to  be  made. 
PLACEJ.OOP  has  no  output  parameters. 

PLACEJ.OOP  does  no  range  checking  on  its  inputs.  This  is  not  a 
problem  as  the  WRITE  routines  pass  BLANKING,  INDEX,  and  BASE  as  con¬ 
stants.  With  the  constants  passed  and  the  input  NUMBER  limited  to  a  single 
WORD  range,  the  inputs  to  PLACE  J.OOP  cannot  be  out  side  defined  ranges.  It 
is  assumed  that  the  correct  LOGICALJJNIT  number  is  passed  into  the  WRITE 
and  WRITELN  routines. 


9.  Output  of  Routines 

The  routines  have  no  output  parameters.  The  only  effect  they  have  on 
the  configuration  of  the  system  is  the  writing  of  a  number  characters  (six  to  seven) 
to  some  logical  unit. 
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a.  Description  of  Test 

These  routines  were  tested  in  conjunction  with  the  rest  of  the  Enhance 
ments  Module  routines  via  the  TESTJT  Module.  Each  Enhancements  Module 
routines  was  given  a  number  of  values  to  output. 


b.  Results  of  Test 

Each  routine  output  its  input  values  in  the  proper  formats. 


11.  Reference  to  Listing 

The  listings  of  WRITE_DWORD,  WRITELN_DWORD,  WRITE_HWORD, 
and  WRITELN_HWORD  are  on  pages  294  in  Appendix  A  and  295  in  Appendix  A. 
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1.  Routine  Name:  WRITE_POINTER  and  WRITELN.POINTER 

2.  Output  routines  of  Enhancements  Module. 

3.  Written  in  PLZ. 

WRITE_POINTER:  five  lines  of  executable  code. 

WR!TELN_POINTER:  three  lines  of  executable  code. 

4.  Synopsis  of  Routines 

These  two  routines  take  a  memory  address  and  output  its  text  string 
equivalent.  The  output  text  string  consists  of  a  "A"  followed  by  four  hexidecimal 
characters  (0  to  9  and  A  to  F).  WRITE_POINTER  does  not  output  a  carriage 
return  and  WRITELN_  POINTER  does.  WRITELN.POINTER  calls  WRITE, 
POINTER  to  perform  the  character  string  output  and  then  calls  PUTCH  to  output 
the  cariage  return. 


5.  Routine  Relationships  Diagram 


Figure  21 .  Relationship  of  Pointer  Write  and  Writeln  Routines 

to  Other  Routines. 
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a.  Invocation  Statement 


The  routines  are  invoked  from  a  calling  PL Z  routine  by: 

WRITE_POINTER(  LOGICALJJNIT,  LOCATION ) 
WRITE LN_P01NTER(  LOGICAL_UNIT,  LOCATION  ) 

where  LOGICAL_UNIT  is  of  type  Byte  and  LOCATION  is  of  type  Word. 


b.  Parameter  Passing  Schema 

Both  routines  have  two  input  parameters,  LOGICALJJNIT  and  LOCA¬ 
TION.  LOGICALJJNIT  is  the  number  of  the  device  the  character  string  is  to  be 
written  to.  LOCATION  holds  the  address  to  be  translated  into  text. 


c.  Routines  Which  Call 

Both  routines  can  be  used  by  any  PLZ  language  program  with  which 
the  Enhancements  Module  and  the  PLZ  Stream.  10  module  have  been  linked. 
The  routines,  like  the  rest  of  the  global  Enhancements  module  routines,  are 
Pascal-like  IO  subroutines  intended  to  reduce  the  difficulty  of  IO  in  PLZ. 


7.  Variables  and  Constants 

a.  Global 

No  global  variables  are  used  by  either  routine.  WRITE_POINTER 
users  no  global  constants.  WRITELN_POINTER  follows  the  PLZ  convention  of 
"%R"  representing  a  carriage  return. 


b.  Module 

Neither  routine  uses  any  module  level  variables.  Within  the  Enhance¬ 
ments  Module,  TRUE  is  a  constant  of  value  01  hex  representing  logical  true  and 
FALSE  is  a  constant  of  value  00  hex  representing  logical  false. 
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c.  Routine 


Routine  level  constants  are  not  used  by  either  routine.  WRITELN_ 
POINTER  has  no  routine  level  variables.  WRITE_POINTER  has  two  routine  level 
variables,  BLANKING  (type  Byte)  and  INDEX  (type  Word).  BLANKING  is  a  logical 
flag  to  routine  PLACEJ.OOP  to  indicate  whether  leading  zeros  are  to  be  blank¬ 
ed.  INDEX  passes  to  PLACE_LOOP  the  place-value  of  the  most  significant 
character  of  the  output  text  string.  These  two  variables  exist  only  to  aid  the 
readability  of  the  code. 


8.  Other  Routines  Called 

Both  WRITE_POINTER  and  WRITELN_POINTER  use  other  Enhance¬ 
ments  Module  routines  to  output  characters.  WRITE_POINTER  uses  the  internal 
routine  PLACE_LOOP  to  perform  the  actual  value  to  character  string  conversion. 

Both  routines  use  the  internal  routine  PUTCH  to  output  single  characters. 

a.  PLACE_LOOP 

PLACE_LOOP  translates  a  value  into  a  string  of  characters  that  repre¬ 
sents  the  value  and  then  outputs  the  characters  to  a  designated  logical  unit. 
PLACE_LOOP  is  invoked  with: 

PLACE_LOOP(  LOGICALJJNIT.  BLANKING,  NUMBER,  INDEX,  BASE) 

where  NUMBER  and  INDEX  are  type  Word  and  LOGICALJJNIT,  BLANKING, 
and  BASE  are  type  Byte.  The  parameter  LOGICALJJNIT  for  PLACEJ.OOP  is 
the  same  as  the  LOGICALJJNIT  input  to  WRITE J’OINTER  and  WRITELN_ 
POINTER.  It  is  the  number  of  the  device  to  which  the  output  will  go.  BLANKING 
is  a  logical  flag  indicating  whether  leaing  zeros  are  to  be  blanked.  NUMBER  is 
the  value  to  be  translated  into  a  string  of  ASCII  characters.  INDEX  hold  the 
place-value  of  the  most  significant  character  of  the  output  string.  BASE  is  the 
desired  base  of  the  character  representation.  PLACE_LOOP  has  no  return 
parameters. 


b.  PUTCH 

PUTCH  outputs  single  characters  to  the  designated  logical  unit. 
PUTCH  has  two  input  parameters,  LOGICALJJNIT  and  CHARACTER.  As  with 
WRITE,  LOGICAL.  UNIT  is  the  Byte  parameter  indicating  which  device  the  output 
is  to  go  to.  CHARACTER,  also  of  type  Byte,  holds  the  ASCII  character  to  be  out¬ 
put.  PUTCH  is  invoked  by: 
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PUTCH(  LOGICAL_UNIT,  CHARACTER ) 

WRITE-POINTER  uses  PUTCH  to  output  the  "A"  and  WRITELN_POIINTER  uses 
PUTCH  to  output  its  carriage  return.  PUTCH  has  no  return  parameters. 


9.  Output  of  Routine 

Neither  routine  has  any  output  parameters.  The  sole  effect  of  the 
routines  upon  the  system  is  the  writing  of  five  characters  and,  if  WRITELN_ 
POINTER,  a  carriage  return  to  the  designated  logical  unit. 


10.  Routine  Testing 

a.  Description  of  Test 

WRITE_POINTER  AND  WRITELN_POINTER  were  tested  along  with 
the  rest  of  Enhancements  module.  This  test  was  accomplished  by  linking  with 
Enhancements  module  and  the  PL Z  STREAM.IO  module  a  module  of  test 
routines. 


b.  Results  of  Test 

WRITE_POINTER  and  WRITELN_POINTER  output  the  correct  text 
strings  to  the  correct  logical  units. 


11.  Reference  to  Listing 

The  listings  of  WRITE_POINTER  and  WRITELN_POINTER  are  on 
page  296  in  Appendix  A. 
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1.  Routine  Names:  WRITE_RCODE  and  WRITELN_RCODE 

2.  Output  routines  of  Enhancements  Modute. 

3.  Written  in  PL Z. 

WRITE_RCODE:  45  lines  of  executable  code. 

WRITELN  RCODE:  3  lines  of  executable  code. 


WRITE_RCODE  and  WRITELN_RCODE  are  PLZ  routines  which  trans¬ 
late  the  RIO  (operating  system)  hexadecimal  error  codes  into  their  text  definitions 
and  outputs  the  text  to  the  system  console.  WRITE_RCODE  is  just  one  big  case 
statement  with  43  cases,  one  case  for  each  RIO  return  code.  WRITE_RCODE  is 
intended  to  be  linked  in  during  program  checkout  for  rapid  diagnosis  of  operating 
system  problems.  WRITE_RCODE  does  not  send  a  carriage  return  to  the  con¬ 
sole.  In  contrast,  WRITELN_RCODE  consists  of  two  subroutine  calls  and  does 
send  a  carrage  return  to  the  console  at  the  end  of  the  text  string. 


Any  PLZ  Routine 


WRITELN  RCODE 


WRITE  RCODE 


WRITE 


WRITELN 


Figure  22.  Relationship  of  WRITE_RCODE  and 
WRITELN  RCODE  to  Other  Routines 
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a.  Invocation  Statement 


WRITE_RCODE  and  WRITELN_RCODE  are  invoked  from  another 
PL Z  routine  via: 


WRITE_RCODE  (  RETURN_CODE  )  and 
WRITELN_RCODE(  RETURN_CODE ) 

where  RETURN_CODE  is  the  RIO  code  in  question.  WRITE_RCODE  and 
WRITELNJRCODE  must  either  be  linked  in  and  declaired  as  an  external 
procedure  or  be  compiled  with  the  calling  PLZ  routine. 


b.  Parameter  Passing  Schema 

WRITE_RCODE  and  WRITELN_RCODE  both  have  one  input  para¬ 
meter,  RETURN_CODE,  of  type  Byte.  If  either  routine  is  passed  an  undefined 
RETURN_CODE,  the  routine  executes  without  taking  any  action.  See  the  routine 
listing  for  the  defined  return  codes  and  their  text  definitions. 


c.  Routines  Which  Call  WRITE_RCODE  and  WRITE  LN_RCODE 

WRITE_RCODE  and  WRITELN_RCODE  can  be  called  by  any  PLZ 
program  they  are  linked  with  or  compiled  with.  WRITE_RCODE  is  called  by 
WRITELN  RCODE  to  translate  the  RETURN  CODE  into  text. 


7.  -Variables  and  Constants 

a.  Global 

Both  routines  use  the  constant  "%R*,  the  PLZ  representation  for  a 
carriage  return.  %R  indicates  to  routines  WRITE  and  WRITELN  the  end  of  the 
string  to  be  output.  Neither  routine  uses  any  global  variables. 


b.  Internal  to  the  Module 

CONSOLE_OUT,  a  constant  of  value  two,  is  used  by  both  WRITE_ 
RCODE  and  WRITELN_RCODE.  It  is  the  logical  unit  number  for  the  system 
console.  Neither  routine  uses  any  module  level  variables. 
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c.  Internal  to  the  Routine 


Neither  WRITE_RCODE  nor  WR1TELN_RC0DE  use  any  routine  level 
variables  or  constants. 


8.  Other  Routines  Called 

WRITE_RCODE  calls  the  routine  WRITE  and  WRITELN_RCODE  calls 
WRITELN  to  output  the  text  translation  of  the  return  codes  to  the  system  console. 
WRITE  and  WRITELN  are  also  part  of  Enhancements  Module. 

WRITE  and  WRITELN  have  two  input  parameters,  LOGICALJJNIT, 
type  byte,  and  TEXT_POINTER,  type  PByte  for  pointer  to  byte.  For  both  routines, 
LOGICALJJNIT  is  always  CONSOLEJDUT  or  2.  TEXT_POINTER  points  to  the 
first  character  of  the  text  string  listed  in  each  case  of  WRITE_RCODE  and  the 
carriage  return,  %R,  for  WRITELN_RCODE.  WRITE  and  WRITELN  are  invoked 
via: 


WRITE  (  LOGICALJJNIT,  #*text  string  %R' )  and 

WRITE LN{  LOGICALJJNIT,  #text  string  %R‘ ) 

where  %R  indicates  the  end  of  the  string  and  the  #  is  the  PLZ  indicator  for  a 
pointer  to  a  string  delimited  by  single  quotes. 


9.  Output  of  Routing 

WRITE_RCODE  and  WR!TELN_RCODE  have  no  output  parameters 
as  such  though  it  does  output  text  to  the  system  console.  Neither  routine  alters 
the  configuration  of  the  system. 


II?.  Bflutinalssiifla 

No  specific  tests  were  created  for  WRITE_RCODE  and  WRITELN_ 
RCODE.  Rather,  they  were  used  as  designed,  linked  in  with  other  PLZ  programs 
for  diagnosis.  When  errors  occured  and  RIO  codes  were  received,  the  routiness 
translated  the  codes  and  output  the  text  to  the  system  console.  Not  only  did  both 
routines  work,  they  proved  to  be  a  valuable  debugging  aids. 


Enhancements  Module 


89 


/> 


1.  Routine  Name:  READLN 


2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PL Z;  six  lines  of  executable  code. 


READLN  is  input  Enhancement  Module  routine  for  the  PLZ  language; 
its  purpose  is  input  of  text  strings.  READLN  reads  in  ASCII  character  and  places 
them  in  a  buffer.  This  continues  until  a  carriage  return  is  read.  At  that  point, 
READLN  returns  to  the  calling  routine  a  pointer  to  the  last  character  in  the  buffer, 
the  carriage  return. 

This  READLN  is  ment  to  approximate  the  function  of  the  Pascal 
Readln  command.  Unlike  the  Pascal  command,  this  READLN  has  two  input 
parameters  to  indicate  from  which  logical  unit  the  text  is  to  be  read  from  and  to 
provide  a  pointer  to  the  memory  location  where  the  string  will  be  put.  To  let  the 
calling  routine  know  how  long  a  text  string  was  read  in,  this  READLN  returns  a 
pointer  to  the  end  of  the  string.  Again,  unlike  Pascal,  the  calling  routine  must 
ensure  sufficent  buffer  space  to  accomodate  the  input  string.  By  using  this 
READLN,  a  PLZ  program  can  read  in  text  string  far  more  easily  than  would  be 
possible  with  the  GETSEQ  routine  of  the  PLZ  STREAM.IO  module,  though  still  not 
as  easy  as  with  the  Pascal  Readln. 


Figure  23.  Relationship  of  READLN  to  Calling  PLZ  Routines  and  to 

GET  ASCII  CH. 
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a.  Invocation  Statement 

READLN  is  invoked  from  a  calling  PLZ  routine  with: 

OUT_POINTER  :=  READLN(  LOGICAL_UNIT,  TEXT_POINTER  ) 

where  all  OUT_POINTER  and  TEXT_POINTER  are  of  type  PByte  (for  pointer  to 
byte)  and  LOGICAL_UNIT  is  of  type  Byte.  The  calling  program  must  ensure  the 
buffer  pointed  to  by  TEXT_PONTER  is  large  enough  to  accomodate  the  input  text 
string. 


b.  Parameter  Passing  Schema 

READLN  has  two  input  parameters,  LOGICAL_UNIT  and  TEXT_ 
POINTER.  LOGICALJJNIT  passes  the  number  of  the  device  the  text  is  to  read  in 
from.  TEXT_  POINTER  holds  the  beginning  address  of  the  buffer  into  which  the 
input  text  will  be  copied. 


c.  Routines  Which  Call  READLN 

READLN  can  be  used  by  any  PLZ  program  linked  with  the  Enhance¬ 
ments  Module  and  the  PLZ  STREAM.IO  Module.  Alternately,  READLN,  along 
with  the  internal  routines  GET_ASCII_CH  and  GETCH,  could  be  part  of  the 
calling  program's  module.  PLZ  STREAM.IO  will  still  have  to  be  linked  in. 


a.  Global 

READLN  uses  no  declaired  global  constants  or  variables.  However, 
the  buffer  into  which  the  text  string  is  in  a  sense  a  global  buffer. 


b.  Module 

No  module  level  variables  are  used  by  READLN.  The  module 
constant  CARRJAGE_RETURN,  valued  at  0D  hex,  is  used  by  READLN. 
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c.  Routine 


READLN  has  no  constants;  it  uses  one  variable,  PINDEX,  of  type 
PByte  for  Pointer-to-Byte.  PINDEX  is  used  as  a  place  keeper,  pointing  to  the 
current  position  in  the  buffer. 


8.  Other  Routines  Called 

READLN  uses  GET_ASCIl_CH,  and  internal  routine  of  Enhancements 
mod-  ule,  to  read  in  each  character.  GET_ASCII_CH  is  invoked  from  GET_ 
ASCII_CH  by; 


PINDEXA  :=  GET_ASCI!_CH(  LOGICAL_UNIT) 

where  PINDEXA  is  the  byte  pointed  to  by  PINDEX  (and  thus  is  of  type  Byte)  and 
LOGICALJJNIT  is  of  type  Byte.  PINDEXA  is  the  memory  location  into  which  the 
charac-  ter  reterived  by  GET_ASCII_CH  is  placed.  LOGICALJJNIT  is  the  device 
number  the  character  is  read  from. 


9.  Output  of  Routine 

READLN  returns  a  single  parameter  to  the  calling  routine,  OUT_ 
POINTER,  of  type  PByte.  OUT_POINTER  points  to  the  last  character  placed  in  the 
buffer,  the  carriage  return.  Thus,  having  passed  to  READLN  TEXT_PO INTER, 
pointing  to  be  beginning  of  the  buffer,  and  having  received  back  OUT_POINTER, 
the  calling  routine  can  determine  the  length  of  the  string  in  the  buffer.  READLN 
does  not  alter  the  configuration  of  the  system  beyond  changing  a  number  of 
memory  locations  to  the  values  read  in  from  the  logical  unit. 


10.  Routine  Testing 

a.  Description  of  Test 

READLN  and  the  rest  of  the  read  routines  of  the  Enhancements 
Module  were  tested  with  a  special  module  of  test  routines.  One  of  these  routines 
used  READLN  to  get  text  in  from  the  keyboard  and  then  displayed  it  to  the  system 
console. 


b.  Results  of  Test 

READLN  performed  properly. 
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1.  Routine  Name:  READ_HBYTE 

2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PLZ;  seven  lines  of  executable  code. 


4.  Synopsis  of  Routine 

READ_HBYTE  reads  in  from  a  designated  logical  unit  two  characters  repre¬ 
senting  a  8  bit  value  in  hexidecimal  form.  The  routine  translates  the  characters 
into  the  value  and  returns  that  value  to  the  calling  routine.  In  reading  in  the 
character,  READ_HBYTE  accepts  only  valid  hexidecimal  characters  (0  -  9  and  A 
-  F)  rejecting  all  other  characters.  READ_HBYTE  will  keep  reading  in  characters 
until  it  has  read  two  valid  hexidecimal  characters. 


5.  Routine  Relationships  Diagram 


Figure  24.  Relationship  of  READ_HBYTE  to  Other  Routines. 


6- Invocation 

a.  Invocation  Statement 

READ_HBYTE  is  invoked  from  a  calling  PLZ  language  routine  by: 
NUMBER  :=  READ_HBYTE(  LOGICAL_UNIT ) 
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where  both  NUMBER  and  LOGICALJJNIT  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

READ_HBYTE  has  a  single  input  parameter,  LOGICALJJNIT,  which 
holds  the  number  of  the  device  from  which  the  hexidecimal  characters  are  to  be 
read. 


c.  Routines  Which  Call 

READ_HBYTE  can  be  called  by  any  PLZ  routine  that  is  linked  with  the 
En-  hancements  Module  and  the  PLZ  STREAM.IO  module.  Alternately,  this  rou¬ 
tine  (and  the  internal  routines  GET_ASCII_CH,  GETCH,  and  VALID_HEX_CH) 
could  be  part  of  the  calling  routine's  module.  The  STREAM.IO  module  is  still 
required. 


7.  Variables  and  Constants 

a.  Global 

No  global  level  variables  or  constants  are  used  by  RE  AD JH  BYTE. 


b.  Module 

READ  HBYTE  uses  no  module  level  variables  or  constants. 


c.  Routine 

Two  local  variables  are  used  by  READ_HBYTE.  FIRST_TERM  is  the 
first  valid  hexidecimal  character  read  in  and  SECOND_TERM  is  the  second. 
Both  of  these  variables  are  of  type  Byte.  READ_HBYTE  uses  no  routine  level 
constants. 


8.  Other  Routines  Called 

READJHBYTE  calls  three  internal  routines  of  the  Enhancements 
Module,  GET_ASCII_CH,  VALID_HEX_CH,  and  VALUE. 
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a.  GET_ASCH_CH 

This  routine  reads  individual  ASCII  characters  in  from  a  designated 
logical  unit.  It  is  invoked  by: 

CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT  ) 

where  both  CHARACTER  and  LOGICALJJNIT  are  of  type  Byte.  READ JH BYTE 
uses  GET_ASCII_CH  to  get  FIRST JTERM  and  SECOND_TERM. 


b.  VALID_HEX_CH 

This  function  determines  whether  its  input  character  is  a  valid  hexi- 
decimal  character  (0  -  9  or  A  -  F).  If  it  is  valid,  a  logical  TRUE  is  returned,  other¬ 
wise  a  FALSE  is  returned.  VALID_HEX_CH  is  invoked  with: 

VALID_HEX_CH(  CHARACTER ) 

where  CHARACTER  is  of  type  Byte  and  VALID_HEX_CH  returns  as  a  logical 
Byte. 


c.  VALUE 

This  internal  function  of  the  Enhancements  module  translates  a  deci¬ 
mal  or  hexidecimal  ASCII  character  (0  -  9  and  A  -  F  )  into  the  value  it  represents 
and  returns  that  value.  If  VALUE  receives  an  invalid  character,  a  value  of  zero  is 
returned.  The  function  VALUE  is  invoked  by  its  name  as  follows. 

VALUE(  CHARACTER ) 

Both  CHARACTER  and  the  return  VALUE  are  of  type  Byte. 


9.  Output  of  Routine 

READ_HBYTE  has  a  single  return  parameter  and  produces  no 
changes  in  the  system  configruation.  The  return  parameter,  NUMBER,  is  the 
hexidecimal  (8  bit)  value  derrived  from  the  two  characters  read  in. 
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a.  Description  of  Test 

READ_HBYTE  was  tested  along  with  the  rest  of  the  Enhancements 
Module  routines.  In  this  test  READJHBYTE  read  in  some  values  from  the 
keyboard;  the  values  were  then  output  to  the  screen. 


b.  Results  of  Test 

READJHBYTE  properly  input  hexidecimal  values  and  performed  as 
expected  for  all  input  data. 


11.  Reference  to  Listing 

The  listing  for  READJHBYTE  is  on  page  300  in  Appendix  A. 
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1.  Routine  Name:  READ_DBYTE 

2.  Part  of  Enhancements  Module 

3.  Written  in  PL Z;  ten  lines  of  executable  code. 


4.  Synopsis  of  Routine 

READ_DBYTE  reads  three  characters  in  from  a  specified  logical  unit 
and  translates  these  characters  into  the  decimal  value  represented  by  the  chara¬ 
cters.  The  internal  Enhancements  Module  routine  GET_ASCll_CH  is  used  for  the 
character  input.  The  first  character  read  in  must  be  valid  decimal  character,  that 
is  0  through  9.  For  the  first  character,  all  nonvalid  decimal  characters  will  be  re¬ 
jected.  Character  validity  is  checked  by  the  internal  Enhancements  Module  rou¬ 
tine  VALID_DECIMAL_CH.  If  the  second  or  third  character  read  in  are  invalid 
they  will  be  accepted  but  will  not  be  included  in  the  value  calculation.  The  actual 
conversion  of  character  to  value  is  accom-  plished  by  VALUE,  an  internal  routine 
of  the  Enhancements  Module. 


As  a  single  byte  has  a  maximum  value  of  255,  if  the  decimal  chara¬ 
cters  represent  a  value  greater  than  this  overflow  will  occur.  The  calling  routine 
must  guard  against  this  condition  as  READ_DBYTE  does  no  range  checking. 


Figure  25.  Relationship  of  READ_DBYTE  to  Other  Routines. 
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a.  Invocation  Statement 


READ_DBYTE  is  invoked  through  the  following  statement. 
NUMBER  :=  READ_DBYTE(  LOGICAL_UNIT ) 
NUMBER  and  LOGICAL_UNIT  are  both  of  type  Byte. 


b.  Parameter  Passing  Schema 

READJDBYTE  has  a  single  input  parameter,  LOGICALJJNIT,  the 
number  of  the  device  from  which  the  characters  will  be  read. 


c.  Routines  Which  Call 

READ_DBYTE  can  be  called  by  any  PL Z  routine. 


7.  Variables  amLConsIants 

a.  Global 

READ_DBYTE  uses  no  global  variables  or  constants. 


b.  Module 

READ_DBYTE  uses  no  module  level  variables.  The  module  constant 
TRUE  for  logical  true  is  used. 


c.  Routine 

READ_DBYTE  uses  three  internal  variables,  FIRST_TERM, 
SECOND_TERM,  and  THIRD_TERM,  ail  of  type  Byte.  These  three  variables  are 
used  to  hold  the  validated  characters  prior  to  calculating  the  decimal  value  they 
represent.  READ_DBYTE  uses  no  routine  level  constants. 
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READ_DBYTE  uses  three  internal  routines  of  the  Enhancements 
module,  GET_ASCII_CH,  VAUD_DECIMAL_CH,  and  VALUE. 

a.  GET_ASCII_CH 

This  routine  reads  single  characters  in  from  a  specified  logical  unit. 
GET_ASCII_CH  returns  only  valid  ASCII  characters.  The  routine  is  invoked  by: 

CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT ) 

where  both  CHARACTER,  and  LOGICALJJNIT  are  of  type  Byte. 


b.  VALID_DECIMAL_CH 

This  function  checks  a  character  to  determine  whether  it  is  a  0  through 
9.  If  the  input  character  is  a  valid  decimal  character,  VALID_DECIMAL_CH  re¬ 
turns  a  value  of  TRUE.  Otherwise,  a  value  of  FALSE  is  returned.  VALID_ 
DECIMAL_CH  is  invoked  with: 

VALID_DECIMAL_CH(  CHARACTER ) 
where  CHARACTER  and  the  return  VALID_DECIMAL_CH  are  type  Byte. 


c.  VALUE 

This  internal  function  of  the  Enhancements  module  translates  a  deci¬ 
mal  or  hexidecimal  ASCII  character  (0  -  9  and  A  -  F  )  into  the  value  it  represents 
and  returns  that  value.  If  VALUE  receives  an  invalid  character,  a  value  of  zero  is 
returned.  The  function  VALUE  is  invoked  by  its  name  as  follows. 

VALUE ( CHARACTER ) 

Both  CHARACTER  and  the  return  VALUE  are  of  type  Byte. 


9.  Output  ol  Routine 

READ_DBYTE  returns  to  its  calling  routine  a  single  parameter, 
NUMBER,  which  holds  value  translated  from  the  characters.  NUMBER  is  of  type 
Byte.  Other  than  reading  in  a  number  of  characters,  READ_DBYTE  causes  no 
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system  configuration  changes. 


10.  Routine  Testing 

a.  Description  of  Test 

I 

j  READ_DBYTE  was  tested  with  the  rest  of  the  Enhancements  module 

■  routines  via  a  version  of  the  test  module  TESTJT.  In  this  test  values  were  output 

!  though  READ_DBYTE  to  the  system  console. 


1  b.  Results  of  Test 

READJOBYTE  performed  properly. 

i 

I  11.  Reference  to  Listing 

The  program  listing  of  READ_DBYTE  can  be  found  on  page  301  in 
;  Appendix  A. 
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1.  Routine  Name:  READ_BBYTE 

2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PL Z;  thirteen  lines  of  executable  code. 


READ_BBYTE  reads  in  from  a  designated  logical  unit  one  to  eight 
characters  representing  a  8  bit  value  in  binary  form.  The  routine  translates  the 
characters  into  the  value  and  returns  that  value  to  the  calling  routine.  In  reading 
in  the  first  character,  READ_BBYTE  accepts  only  valid  binary  characters  (0  and 
1 )  rejecting  all  other  characters.  READ_BBYTE  will  keep  reading  in  characters 
until  it  has  a  1  or  0.  Subsequent  Is  and  0s  will  be  read  in  and  included  for  the 
value  calculation.  However,  as  soon  as  a  character  other  than  a  1  or  0  is  read, 
character  input  ceases.  The  character  reading  is  accomplished  through  routine 
GET_ASCII_CH. 

READ_BBYTE  stores  the  Is  and  0s  in  a  text  string  which  it  passes  to 
routine  VALUE_LOOP  for  translation  into  a  value.  READ_BBYTE  then  returns 
this  value  to  its  calling  routine. 


Figure  26.  Relationship  of  READ_BBYTE  to  Calling  PLZ  Routine, 
GET_ASCII_CH,  and  VALUE_LOOP. 


Enhancements  Module 


103 


a.  Invocation  Statement 


READ_BBYTE  is  invoked  from  a  calling  PLZ  language  routine  by: 
NUMBER  :=  READ_BBYTE(  LOGICAL_UNIT ) 
where  both  NUMBER  and  LOGICAL_UNIT  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

READ_BBYTE  has  a  single  input  parameter,  LOGlCAL_UNIT,  which 
holds  the  number  of  the  device  from  which  the  hexidecimal  characters  are  to  be 
read. 


c.  Routines  Which  Call 

READ_BBYTE  can  be  called  by  any  PLZ  routine  that  is  linked  with  the 
Enhancements  Module  and  the  PLZ  STREAM.  10  Module.  Alternately,  this  routine 
(and  the  internal  routines  GET_ASCII_CH,  GETCH,  and  VALID_HEX_CH)  could 
be  part  of  the  calling  routine's  module.  The  STREAM.  10  Module  is  still  required. 


a.  Global 


No  global  level  variables  or  constants  are  used  by  READ_BBYTE. 


b.  Module 

READ_BBYTE  uses  no  module  level  variables.  The  Enhancements 
Module  constant  BLANK  (ASCII  for  20  hex)  is  used  by  READ_BE3YTE. 


Routine 


Three  local  variables  are  used  by  READ_BBYTE.  INPUT_STRING,  of 
type  ASCII_STR,  an  array  of  eight  Bytes,  is  used  to  store  the  Is  and  0s.  INDEX, 
of  type  Byte,  is  a  placekeeper  for  the  array  INPUT_STRING.  The  third  variable, 
CHARACTER,  is  used  to  hold  each  character  as  it  is  read  in. 
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READ_BBYTE  calls  two  internal  routines  of  the  Enhancements 
Module,  GET_ASCII_CH  and  VALUE_LOOP. 

a.  GET_ASCII_CH 

This  routine  reads  individual  ASCII  characters  in  from  a  designated 
logical  unit.  It  is  invoked  by: 

CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT ) 

where  both  CHARACTER  and  LOGICALJJNIT  are  of  type  Byte.  RE  AD JB  BYTE 
uses  GET_ASCII_CH  to  read  in  the  characters. 


b.  VALUE J_OOP 

This  routine  translates  a  string  of  ASCII  characters  into  the  value  they 
repre-sent.  VALUE_LOOP  is  invoked  though: 

MAGNITUDE  :=  VALUE_LOOP(  INPUT_STRING,  MULTIPLIER  ). 

VALUE  J.OOP  has  two  input  parameters,  INPUT_STRING  (type  PByte),  a  pointer 
to  the  string  of  ASCII  characters,  and  MULTIPLIER  (type  Word)  the  base  of  the 
number  represented  by  the  string  of  characters.  Starting  from  the  least  significant 
character  VALUE_  LOOP  calculates  the  value  contributed  by  each  character  to 
the  total  MAGNITUDE  represented  by  the  string.  The  routine  ends  when  a  blank 
is  found  in  the  INPUT_STRING  or  when  eight  characters  have  been  translated. 
VALUEJ.OOP  has  a  single  return  parameter,  MAGNITUDE,  of  type  Word. 


9.  Output  of  Routine 

READ_BBYTE  has  a  single  return  parameter  and  produces  no 
changes  in  the  system  configuration.  The  return  parameter,  NUMBER,  is  the 
hexidecimal  (8  bit)  value  derrived  from  the  Is  and  0s  read  in. 


Enhancements  Module 


105 


a.  Description  of  Test 


READ_BBVTE  was  tested  along  with  the  rest  of  the  Enhancements 
Module  routines.  In  this  test  READ_BBYTE  read  in  some  values  from  the  key¬ 
board;  the  values  were  then  output  to  the  screen. 


b.  Results  of  Test 

READ_BBYTE  properly  read  in  binary  values  and  converted  them  to 
the  proper  values. 

1 1 .  Reference  to  Listing 

The  listing  of  READ_BBYTE  is  on  page  302  in  Appendix  A. 
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1.  Routine  Name:  READ_LBYTE 

2.  Output  routine  of  Enhancements  Module 

3.  Written  in  PLZ;  seven  lines  of  executable  code. 


4.  Synopsis  of  Routine 

This  simple  routine  reads  in  characters,  on  at  a  time,  from  a  desig¬ 
nated  logical  unit.  It  the  character  is  a  T,  t,  or  1,  a  value  of  logical  true  is  returned 
to  the  calling  routine.  If  the  character  is  a  F,  f,  or  0  a  value  of  logical  false  is  re¬ 
turned  to  the  calling  routine.  If  any  other  character  input,  the  routine  loops  and 
another  character  is  read  in.  READ__LBYTE  uses  the  internal  Enhancements 
module  routine  GET_ASC1I_CH  to  read  in  the  character(s). 


5,  Routine  Relationships  Diagram 


Figure  27.  Relationship  of  READ_LBYTE  to  Calling  Routines 
and  to  GET_ASCII_CH. 


6„.  invocation 

a.  Invocation  Statement 

READ_LBYTE  is  invoked  by  the  following  statement. 
TRUTH  :=  READ_LBYTE(  LOGICALJJNIT) 
Both  the  input  and  return  parameters  are  of  type  Byte. 
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b.  Parameter  Passing  Schema 


READ_LBYTE  has  one  input  parameter,  LOGICALJJNIT,  the  device 
number  from  which  the  character  will  be  read. 


c.  Routines  Which  Call 

READ_LBYTE,  like  the  rest  of  the  global  routines  of  the  Enhance¬ 
ments  Module,  are  ment  to  be  called  from  any  PL Z  routine  that  needs  10 
assistance. 


7.  Variables  and  Constants 

a.  Global 

READ_LBYTE  uses  no  global  constants  or  variables. 


b.  Module 

READ_LBYTE  uses  the  module  constants  TRUE  and  FALSE  for 
logical  true  and  false.  Pie  routine  uses  no  module  level  variables. 


c.  Routine 

READJJBYTE  employes  the  local  variable  CHARACTER,  of  type  Byte, 
to  hold  the  character  read  in.  The  routine  has  no  locally  defined  constants. 


8.  Other  Routines  Called 

READ_LBYTE  calls  GET_ASCII_CH,  an  internal  routine  of  the 
Enhancements  module,  to  read  in  the  character  input.  GET_ASCII_CH  is 
invoked  by: 

CHARACTER  :=  GETJ\SCII_CH(  LOGICALJJNIT ) 

where  both  the  input  parameter  LOGICALJJNIT  and  the  return  character 
CHARACTER  are  of  type  Byte.  LOGICALJJNIT  holds  the  input  device  number. 
CHARACTER  holds  the  character  input.  GET_ASCII_CH  returns  only  valid  ASCII 
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characters. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

READ_LBYTE  has  a  single  return  parameter,  TRUTH,  of  type  Byte. 
TRUTH  returns  the  logical  value  derived  from  the  read  character.  TRUTH  can 
take  on  only  the  values  TRUE  or  FALSE. 


b.  System  Configuration  Changes 

The  routine  causes  no  system  configuration  changes  aside  from 
reading  in  a  character. 


10.  Routing  Testing 

a.  Description  of  Test 

READ_LBYTE  was  tested  in  the  same  fashion  as  the  rest  of  the  En¬ 
hancements  Module  routines. 


b.  Results  of  Test 

The  routine  performed  properly. 


11.  Reference  to  Listing 

The  program  listing  of  READ_LBYTE  is  on  page  303  in  Appendix  A. 
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1.  Routine  Name:  READ_DINTEGER 

2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PL 2;  22  lines  of  executable  code. 


4.  Svnoosis  of  Routine 

READ_DINTEGER  reads  in  a  string  of  characters  from  the  designated 
logical  unit  and  translates  that  string  into  a  signed  value.  The  routine  begins  by 
calling  GET_ASCII_CH  to  read  in  the  sign  character.  Characters  are  read  in  from 
the  desired  logical  unit  until  a  blank, or is  read  in,  these  three  being  the 
valid  sign  characters.  The  sign  character  read  is  saved  in  the  local  variable 
SIGN. 

The  routine  continues  reading  in  individual  characters  until  a  valid 
decimal  character  (0  through  9)  is  read,  the  validity  of  characters  is  checked  by 
the  function  routine  VALID_DECIMAL_CH.  The  first  valid  decimal  character 
received  becomes  the  first  character  stored  in  the  local  array  INPUT_STRING. 
READ_DINTEGER  continues  reading  in  characters.  The  reading  process  stops 
with  the  first  invalid  decimal  character  or  when  a  total  of  five  decimal  charactes 
have  been  read.  When  an  invalid  character  is  read  or  after  five  valid  characters 
have  been  read,  a  blank  is  inserted  into  INPUT_  STRING.  The  valid  decimal 
charactes  are  insterted  into  INPUTJSTRING  in  the  order  they  are  received. 

READ_DINTEGER  then  enters  its  third  phase,  the  translation  of  SIGN 
and  INPUT_STRING  into  the  return  parameter  NUMBER,  of  type  Integer.  The 
bulk  of  the  work  is  done  by  general  routine  VALUE_LOOP  which  translates  the 
characters  of  INPUT_STRING  into  the  base  ten  value  they  represent.  This  value 
is  checked  for  over-  flow  and  then,  if  SIGN  is  the  value  is  negated.  NUMBER 
is  then  returned  to  the  calling  routine. 
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> 

5.  Routine  Relationships  Diagram 


l 


f 


Figure  28.  Relationship  of  READ_DINTEGER  to  Other 

Routines. 


6.  Invocation 

a.  Invocation  Statement 

READ_DINTEGER  is  invoked  from  a  calling  PLZ  program  through: 
NUMBER  :=  READ_DINTEGER(  LOGICAL_UNIT ) 
where  LOGICAL_UNIT  is  of  type  Byte  and  NUMBER  is  type  Integer. 


b.  Parameter  Passing  Schema 

LOGICALJJNIT  is  READ_DINTEGER's  only  input  parameter.  It  holds 
the  number  of  the  device  the  characters  are  input  from. 


c.  Routines  Which  Call 

READ_DINTEGER  can  be  employed  by  any  PLZ  program  linked  with 
the  Enhancements  Module  and  the  PLZ  STREAM.  10  Module. 


* 
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a.  Global 


No  global  variables  or  constants  are  used  by  READ_DINTEGER. 


b.  Module 

READ_DINTEGER  uses  the  Enhancements  Module  constants  BLANK, 
TRUE,  and  FALSE.  No  module  level  variables  are  used. 


c.  Routine 

READ_DINTEGER  has  four  internal  variables.  INPUT_STRING,  type 
ASCII_STR  (a  string  of  8  bytes)  is  used  to  hold  the  input  characters.  INDEX,  type 
Byte,  is  a  placekeeper  for  the  array  INPUT_STRING.  CHARACTER,  type  Byte, 
hold  each  character  as  they  are  read  in.  Lastly,  SIGN,  type  Byte,  holds  the  chara¬ 
cter  representing  the  sign  of  the  input  string.  READ_DINTEGER  uses  no  locally 
defined  constants. 


8.  Other  Routines  Called 

READ_DINTEGER  employes  three  internal  routines  from  the 
Enhancements  Module,  GET_ASCII_CH,  VALID  DECIMAL_CH,  and 
VALUE  LOOP. 


a.  GET_ASCII_CH 

This  routine  reads  single  characters  in  from  a  specified  logical  unit 
and  returns  them  to  the  calling  routine.  GET_ASCII_CH  returns  only  valid  ASCII 
characters.  The  routine  is  invoked  by: 

CHARACTERS  :=  GET_ASCII_CH(  LOGICALJJNIT ) 
where  both  CHARACTER  and  LOGICALJJNIT  are  of  type  Byte. 


b.  VALID_DECIMAL_CH 

This  function  routine  determines  whether  a  character  is  a  0  though  9. 
If  yes,  VALID_DECIMAL_CH  returns  with  a  value  of  TRUE.  Otherwise  VALID_ 
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DECIMAL_CH  returns  with  a  value  of  FALSE.  The  routine  is  invoked  with: 
VALID_DECIMAL_CH(  CHARACTER  ) 

where  both  CHARACTER  and  the  returning  VAL!DE_DECIMAL_CH  are  type 
Byte. 


c.  VALUE_LOOP 

VALUE_LOOP  translates  a  string  of  ASCII  characters  into  the  value 
they  represent  and  returns  that  value  to  the  calling  routine.  Being  a  general 
purpose  routine,  VALUE_LOOP  must  be  told  what  base  the  representation  is  in. 
In  general,  VALUE_  LOOP  is  invoked  by: 

MAGNITUDE  :=  VALUE_LOOP(  INPUT_STRING,  MULTIPLIER  ) 

where  NUMBER  is  type  Word,  INPUT_STRING  is  type  pointer-to-Byte,  and 
MULTIPLIER  is  type  Word.  As  the  output  of  READ_DINTEGER  is  of  type  Integer, 
for  READ_  DINTEGER,  VALUE_LOOP  is  invoked  with  a  type  conversion.  As 
READ_DINTEGER  is  converting  a  decimal  string,  MULTIPLER  is  passed  in  as  10 
for  the  base. 


9,  Output  of  Routine 

a.  Parameter  Passing  Schema 

READ_DINTEGER  has  a  single  return  parameter,  NUMBER  (type 
Integer),  which  holds  the  value  translated  from  the  string  of  input  characters. 

b.  System  Configuration  Changes 

No  system  configuration  changes  are  caused  by  READ_DINTEGER. 


10.  Routine  Testing 

a.  Description  of  Test 

READ_DINTEGER  was  tested  with  a  version  of  TESTJT  module.  In 
this  version,  READ_DINTEGER  was  called  from  TESTJT  to  read  an  decimal 
integer  in  from  the  system  keyboard.  The  return  from  READ_DINTEGER  was 
then  output  to  the  system  console.  Thus  the  operator  could  input  a  variety  of 
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characters  and  observe  the  response  of  READ_DINTEGER. 
b.  Results  of  Test 

READ_DINTEGER  performed  as  expected. 

11.  Reference  to  Listing 

The  listing  of  READ_DINTEGER  is  on  pages  304  *  305  in  Appendix  A. 
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1.  Routine  Name:  READ_HWORD 

2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PLZ;  1 4  lines  of  executable  code. 

4.  Svnoosis  oLRoutine 

READ_HWORD  is  an  Enhancements  module  routine  whose  function 
is  to  input  a  sequence  of  characters  and  translate  that  that  sequence  into  the 
hexidecimal  value  it  represents.  The  routine  begins  by  reading  in  characters, 
one  by  one,  until  a  valid  hexidecimal  character  is  received.  The  input  is  handled 
by  the  routine  GET_ASCII_CH.  The  characters  are  checked  by  VALID_HEX_CH 
to  determine  whether  the  character  is  a  0  to9  or  A  to  F.  Once  a  valid  hexidecimal 
is  received,  it  is  the  first  character  stored  in  the  internal  array  INPUT_STRINT. 
READJHWORD  then  continues  reading  in  chracters,  one  by  one.  Each  succes¬ 
sive  valid  hexidecimal  character  is  stored  in  INPUT_STRING  until  four  character 
are  stored.  If  a  nonvalid  character  is  read,  a  blank  is  placed  in  INPUT_STRING 
and  input  is  ended. 

READJHWORD  next  proceeds  to  translating  the  characters  stored  in 
INPUT_STRING  into  the  hexidecimal  value  they  represent.  The  work  is  done  by 
routine  VALUE_LOOP.  The  derived  16  bit  value  is  returned  to  the  calling  routine 
in  the  output  parameter  NUMBER,  type  Word. 

5.  Routine  Relationships  Diagram 


Figure  29.  Relationship  of  READJHWORD  to  Other  Routines. 
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a.  Invocation  Statement 


From  a  PLZ  program,  READ_HWORD  is  invoked  by: 
NUMBER  :=  READ_HWORD(  LOGICAL_UNIT ) 
where  NUMBER  is  type  Word  and  LOGICAL_UNJT  is  type  Byte. 


b.  Parameter  Passing  Schema 

READ_HWORD  has  a  single  input  parameter,  LOGICALJJNIT. 
LOGICAL_  UNIT,  type  Byte,  holds  the  number  of  the  device  from  which  the 
characters  are  read. 


c.  Routines  Which  Call 

Like  the  rest  of  the  Enhancements  Module  routines,  READ_HWORD  is 
an  supplement  routine  ment  to  ease  the  10  burden  on  PLZ  programmers.  READ. 
HWORD  can  be  called  from  any  PLZ  program  linked  with  the  Enhancements 
Module  and  the  PLS  STREAM.  10  Module. 


Z,._Variable.S-and  Constants 

a.  Global 

No  global  variables  or  constants  are  used  by  READ.HWORD. 

b.  Module 

READ.HWORD  uses  the  Enhancements  moudle  constants  TRUE  and 
FALSE  for  logical  true  and  false.  No  module  level  variables  are  used. 


c.  Routine 

Three  variables  are  local  to  READ_HWORD,  INPUT_STRING  (type 
ASCII.  STRing),  INDEX  (type  Byte),  and  CHARACTER  (type  Byte).  INPUT. 
STRING  is  an  eight  Byte  array  used  to  hold  the  up  to  five  characters  (four  hex 
characters  and  a  blank)  read  in.  INDEX  is  a  place  keeper  for  the  current  location 
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being  used  in  INPUT_STRING.  CHARACTER  receives  the  individual  characters 
read  in  via  GET_ASCII_CH.  READ_HWORD  uses  no  locally  defined  constants. 


8.  Other  Routines  Called 

READJHWORD  uses  three  internal  routines  of  the  Enhancements 
Module:  GET_ASCII_CH,  VALID_HEX_CH,  and  VALUE_LOOP. 

a.  GET_ASCII_CH 

This  routine  reads  in  a  single  character  from  a  specified  logical  unit, 
checks  to  ensure  the  character  is  valid  ASCII,  and  returns  the  character  to  the 
calling  routine.  GET_ASCII_CH  keeps  reading  in  data  until  a  valid  ASCII  chara¬ 
cter  is  received.  GET_ASCII_CH  is  invoked  with: 

CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT ) 

where  CHARACTER  and  LOGICALJJNIT  are  both  type  Byte.  The  input  para¬ 
meter,  LOGICAL_UNIT,  indicates  the  device  to  be  used  for  input.  CHARACTER, 
the  return  parameter,  holds  the  valid  ASCII  character  read  in  from  the  LOGICAL_ 
UNIT. 


b.  VALID  HEX  CH 


This  Enhancements  module  internal  function  format  routine,  checks 
whether  a  character  is  a  0  to  9  or  A  to  F.  If  yes,  VALID_HEX_CH  returns  to  the 
calling  routine  with  a  value  of  TRUE.  If  the  character  passed  to  VALID_HEX_CH 
is  not  a  valid  hexidecimal  character,  VALID_HEX_CH  returns  to  the  calling  rou¬ 
tine  as  FALSE.  VALID_HEX_CH  is  invoked  through: 


VALID_HEX_CH(  LOGICALJJNIT ) 


I 


where  LOGICALJJNIT,  type  Byte,  identifies  the  device  from  which  data  is  to  be 
read. 


c.  VALUE  LOOP 


VALUE_LOOP  is  a  general  purpose  translation  routine.  It  takes  a 
string  of  characters,  in  any  base  from  2  to  16,  and  translates  the  string  into  the 
value  they  represent.  VALUE  J.OOP  is  invoked  by: 


MAGNITUDE  :-  VALUE_LOOP(  INPUT_STRING,  MULTIPLER  ) 
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where  MAGNITUDE  (type  Word)  is  the  value  represented  by  the  characters, 
INPUT_  STRING  (type  pointer-to-string)  is  the  string  of  characters,  and 
MULTIPLIER  (type  Word)  is  the  base  of  the  character  representation. 


READ_HWORD  has  a  single  output  parameter,  NUMBER,  of  type 
Word.  NUMBER  holds  value  translated  from  the  input  characters.  The  defined 
range  of  NUMBER  is  0000  to  FFFF  hexidecimal.  READ_HWORD  causes  no 
configuration  changes. 


Description  of  Test 


READ_HWORD  was  tested  through  a  routine  in  version  of  TESTJT 
Module  which  uses  READ_HWORD  to  read  in  characters  from  the  keyboard  and 
translate  them  into  a  value.  This  value  is  then  displayed  to  the  system  console. 
This  way,  the  function  of  READ_HWORD  can  be  immediately  observed. 


b.  Results  of  Test 


READ_HWORD  worked  properly. 


READJHWORD's  program  listing  is  on  page  306  in  Appendix  A. 
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1.  Routine  Name:  READ_DWORD 

2.  Output  routine  of  Enhancements  Module. 

3.  Written  in  PLZ;  14  lines  of  executable  code. 


READ_DWORD  is  an  Enhancements  Module  routine  whose  function 
is  to  input  a  sequence  of  characters  and  translate  that  that  sequence  into  the 
decimal  value  it  represents.  The  routine  begins  by  reading  in  characters,  one  by 
one,  until  a  valid  decimal  character  is  received.  The  input  is  handled  by  the  rou¬ 
tine  GET_ASCII_CH.  The  characters  are  checked  by  VALID_DECIMAL_CH  to 
determine  whether  the  character  is  a  0  to9.  Once  a  valid  decimal  is  received,  it  is 
the  first  character  stored  in  the  internal  array  INPUT_STRING.  READJDWORD 
then  continues  reading  in  chracters,  one  by  one.  Each  successive  valid  decimal 
character  is  stored  in  INPUT_STRING  until  six  character  are  stored.  If  a  nonvalid 
character  is  read,  a  blank  is  placed  in  INPUT_STRING  and  input  is  ended. 

READ_DWORD  next  proceeds  to  translating  the  characters  stored  in 
INPUT_STRING  into  the  decimal  value  they  represent.  The  work  is  done  by  rou¬ 
tine  VALUE_LOOP.  The  derived  16  bit  value  is  returned  to  the  calling  routine  in 
the  output  parameter  NUMBER,  type  Word. 


Figure  30.  Relationship  of  READ_DWORD  with  Other  Routines 
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a.  Invocation  Statement 


From  a  PL Z  program,  READ_DWORD  is  invoked  by: 
NUMBER  :=  READ_DWORD(  LOGICALJJNIT  ) 
where  NUMBER  is  type  Word  and  LOGICALJJNIT  is  type  Byte. 


b.  Parameter  Passing  Schema 

READ_DWORD  has  a  single  input  parameter,  LOGICALJJNIT. 
LOGICAL_  UNIT,  type  Byte,  holds  the  number  of  the  device  from  which  the 
characters  are  read. 


c.  Routines  Which  Call 

Like  the  rest  of  the  Enhancements  module  routines,  READ.DWORD  is 
a  supplement  routine  ment  to  ease  the  10  burden  during  PLZ  programming. 
READ.  DWORD  can  be  called  from  any  PLZ  program  linked  with  the 
Enhancements  module  and  the  PLS  STREAM.  10  module. 


7.  Variables  and  Constants 

a.  Global 

No  global  variables  or  constants  are  used  by  READ.DWORD. 

b.  Module 

READ_DWORD  uses  the  Enhancements  module  constants  TRUE, 
FALSE,  and  BLANK.  No  module  level  variables  are  used. 


c.  Routine 

Three  variables  are  local  to  READ_DWORD,  INPUT_STRING  (type 
ASCII.  STRing),  INDEX  (type  Byte),  and  CHARACTER  (type  Byte).  INPUT. 
STRING  is  an  eight  Byte  array  used  to  hold  the  up  to  seven  characters  (six  deci¬ 
mal  characters  and  a  blank)  read  in.  INDEX  is  a  place  keeper  for  the  current 


Enhancements  Module  1 20 


location  being  used  in  INPUT_STRING.  CHARACTER  receives  the  individual 
characters  read  in  via  GET_ASCII_CH.  READ_  DWORD  uses  no  locally  defined 
constants. 


8.  Other  Routines  Called 

READ_DWORD  uses  three  internal  routines  of  the  Enhancements 
Module:  GET_ASCII_CH,  VALID_DECIMAL_CH,  and  VALUE_LOOP. 

a.  GET_ASCII_CH 

This  routine  reads  in  a  single  character  from  a  specified  logical  unit, 
checks  to  ensure  the  character  is  valid  ASCII,  and  returns  the  character  to  the 
calling  routine.  GET_ASCII_CH  keeps  reading  in  data  until  a  valid  ASCII  chara¬ 
cter  is  received.  GET_  ASCII_CH  is  invoked  with: 

CHARACTER  :=  GET_ASCII_CH(  LOGICALJJNIT  ) 

where  CHARACTER  and  LOGICALJJNIT  are  both  type  Byte.  The  input  para¬ 
meter,  LOGICALJJNIT,  indicates  the  device  to  be  used  for  input.  CHARACTER, 
the  return  parameter,  holds  the  valid  ASCII  character  read  in  from  the  LOGICAL_ 
UNIT. 


b.  VALID_DECIMAL_CH 

This  Enhancements  Module  internal  function  format  routine,  checks 
whether  a  character  is  a  0  to  9.  If  yes,  VALID_DECIMAL_CH  returns  to  the 
calling  routine  with  a  value  of  TRUE.  If  the  character  passed  to  VALIDJDECI- 
MAL_CH  is  not  a  valid  decimal  character,  VALID_DECIMAL_CH  returns  to  the 
calling  routine  as  FALSE.  VALID_DECIMAL_CH  is  invoked  through: 

VALID_DECIMAL_CH(  LOGICALJJNIT  ) 

where  LOGICALJJNIT,  type  Byte,  identifies  the  device  from  which  data  is  to  be 
read. 


c.  VALUEJ.OOP 

This  Enhancements  Module  routine  is  a  general  purpose  translation 
routine.  It  takes  a  string  of  characters,  in  any  base  from  2  to  1 6,  and  translates  the 
string  into  the  value  they  represent.  VALUE_LOOP  is  invoked  by: 


r"“  •»  '  ^  **'  J'  -  *  J*  J-  ,N  ■'  J. 

^  ^  ^ ^  »  ^  ’  -  * mJX - 
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MAGNITUDE  :=  VALUE_LOOP(  INPUT_STRING,  MULTIPLER  ) 

where  MAGNITUDE  (type  Word)  is  the  value  represented  by  the  characters, 
INPUT_  STRING  (type  pointer-to-string)  is  the  string  of  characters,  and  MULTI¬ 
PLIER  (type  Word)  is  the  base  of  the  character  representation.  VAUE_LOOP 
performs  a  crude  overflow  checking  and  returns  the  maximum  16  bit  value 
(65,535  decimal)  if  overflow  is  detected. 


9.  Output  of  Routine 

READ_DWORD  has  a  single  output  parameter,  NUMBER,  of  type 
Word.  NUMBER  holds  value  translated  from  the  input  characters.  The  defined 
range  of  NUMBER  is  0  to  65,535  decimal.  READ_DWORD  causes  no  config¬ 
uration  changes. 


10.  Routine  Testing 


a.  Description  of  Test 

READ_DWORD  was  tested  through  a  routine  which  used  READ_ 
DWORD  to  read  decimal  characters  in  from  the  keyboard  and  translate  them  into 
a  value.  This  value  was  then  displayed  to  the  system  console.  Thus,  the  function 
of  READ_DWORD  was  immediately  observed. 


b.  Results  of  Test 

READ_DWORD  worked  properly. 


11.  Reference  to  Listing 

The  listing  of  routine  READ_DWORD  is  on  page  307  in  Appendix  A. 
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Introduction  to  Utility  Module 


Utility  Module  is  a  collection  of  nine  Z-80  assembly  language  routines 
designed  to  give  PLZ  language  programs  direct  access  to  input/output  ports,  spe¬ 
cific  memory  locations,  the  CPU  interrupt  enable/disable,  the  system  date,  and 
the  RIO  Operating  System  memory  manager.  These  assembly  language  routines 
are  called  as  subroutines  from  PLZ  programs.  The  routines  of  the  Utility  Module 
and  their  functions  are: 

IOOUT:  Outputs  desired  value  to  desired  10  port. 

IOIN:  Reads  input  from  desired  10  port. 

MEMSET:  Writes  a  desired  value  to  a  specific  memory  cell. 

MEMREAD:  Reads  the  value  stored  in  a  specific  memory  cell. 

DISABLEINT:  Disables  the  CPU  maskable  interupts 

ENABLEINT:  Enables  the  CPU  maskable  interupts 

DATE:  Reads  the  six  characters  of  the  system  date. 

ALLOCATE:  Calls  the  memory  manager  for  allocation  of 

a  specific  sized  block  of  memory. 

DEALLOCATE:  Calls  the  memory  manager  for  the  deallocation 

of  a  specific  block  of  memory. 

Figure  31  below  shows  how  these  nine  routines  relate  to  the  their  calling  PLZ 
routines  and  to  elements  of  the  development  system. 

Seven  of  the  nine  Utility  Module  routines  share  several  common 
features  mandated  by  the  PLZ  subroutine  call  and  parameter  passing  procedures 
(Ref  6:Sec  7).  These  features  are: 

1 .  Saving  the  current  IX  register  value, 

2.  Placing  the  stack  pointer  value  in  the  IX  register  and  using 
offsets  for  access  to  input  and  output  parameters, 

3.  Code  to  accomplish  the  routine's  specific  task, 

4.  Restoring  of  calling  routine's  IX  register  value, 

5.  Deallocating  of  input  parameter  space  on  the  stack,  and 

6.  Returning  to  the  calling  PLZ  routine. 

The  program  listings  for  the  seven  routines  are  organized  like  the  above  feature 
listing  with  blank  lines  setting  off  the  PLZ  overhead  from  the  routine's  function 
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code.  Two  routines  of  the  Utility  Module,  ENABLEINT  and  DISABLEINT  do  not 
share  the  common  tea-  tures  listed  above.  This  is  due  to  their  lack  of  input  and 
output  parameters  and  their  sim-  plicty;  they  just  do  not  require  the  overhead  of 
the  other  seven  routines.  The  reasons  for  and  the  form  of  this  overhead  of  the 
other  seven  routines  is  detailed  below. 


Any  PL Z  Language  Routines 

V _ / 


UTILITY  Module 
Routines 


ALLOCATE  & 
DEALLOCATE 


MEMSET  & 
MEMREAD 


DATE 


IOIN& 

IOOUT 


ENABLEINT  & 
DISABLEINT 


RIO  Operating  System 


Memory  Manager 


S 


System 

Memory 


IO  Ports 


Z-80  CPU 


Figure  31 .  Relationship  Between  the  Routines  of  the  Utility  Module  to 
Calling  Routines  and  System  Elements. 


The  first  action  of  the  seven  routines  is  to  save  the  current  value  of  the 
IX  register  by  pushing  it  onto  the  stack  This  is  vital.  The  IX,  upon  entry  to  the 
Utility  Module  routine,  points  to  the  calling  routine's  parameters  and  must  be 
restored  if  the  overall  pro-  gram  is  to  properly  execute  upon  return  from  the  Utility 
Module  routine.  ENABLEINT  and  DISABLEINT  do  use  the  IX  register  and  thus 
do  not  have  to  save  its  contents. 

Next,  the  current  stack  pointer  value  is  placed  in  the  IX  register.  Off- 
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sets  from  IX  will  be  used  throughout  the  routines  to  access  and  save  input  and 
output  parameters  respectively.  PLZ  uses  a  table  called  an  Activation  Record 
(AREC)  to  pass  parameters  between  calling  routines  and  subroutines.  The 
AREC  is  placed  on  the  system  stack  by  the  calling  routine.  The  AREC  contains 
(from  high  address  to  low  address): 

1.  Output  or  Return  Parameters, 

2.  Input  Parameters, 

3.  Local  Parameters  (of  the  called  routine),  and 

4.  A  Mark-Stack  Record  (MREC)  consisting  of  the  return  address  of  the 
calling  routine  and  the  IX  register  value  of  the  calling  routine. 

For  the  Utility  Module  routines,  there  are  no  local  parameters.  Upon  entry  to  the 
called  routine,  the  stack  pointer  will  point  to  the  low  memory  boundry  of  the 
AREC.  Thus  by  loading  it  into  the  IX  register,  offsets  can  be  easily  used. 

The  amount  of  offset  from  the  IX  depends  upon  the  number  and  size 
of  values  present  in  the  AREC  (Ref  6:7-2).  For  example,  variables  of  PLZ  type 
Byte  require  only  one  location  (one  byte)  in  the  AREC  while  variables  of  type 
Word  require  two  locations.  Return  parameters  however,  are  always  passed  in 
sixteen  bit  forms,  reguardless  of  type.  Strings  are  handled  by  passing  pointers 
(sixteen  bits)  to  the  beginning  of  the  string.  Figure  32  below  gives  an  example  of 
the  AREC  for  ALLOCATE,  the  Utility  Module  routine  having  the  most  complex  set 
of  parameters.  Note  that  the  return  parameter  RETURN_  CODE  is  passed  in  a 
sixteen  bit  space  dispite  it  being  of  type  byte  and  requiring  only  eight  bits. 

The  third  section  of  the  seven  Utility  Module  routines  is  the  unique 
code  of  each  routine  uses  to  accomplish  its  function.  While  different  in  purpose, 
the  code  of  the  seven  Utility  Module  routines  share  the  use  of  offsets  from  the  IX 
register  to  access  input  parameters  and  to  load  output  parameters. 

The  fourth  common  feature  of  the  seven  routines  is  the  restoration  of 
the  calling  routine's  IX  register  through  a  POP  IX  instruction.  This  instruction  flags 
the  end  of  the  routine  function  code  and  the  beginning  of  the  final  three  PLZ  over¬ 
head  management  steps. 

The  next  to  last  step  is  the  deallocation  of  input  parameter  (in  PLZ 
parlance  these  are  out  parameters)  storage  space  on  the  stack.  As  with  saving 
the  IX  value,  this  action  is  vital.  Upon  return  to  the  calling  routine,  PLZ  expects 
to  find  the  return,  local,  and  all  other  parameters  needed  by  the  calling  routine  as 
off  sets  from  the  stack  pointer.  It  the  dealllocation  of  input  parameters  isn't  ac¬ 
complished,  all  the  stack  pointer  offsets  will  be  invalid.  ENABLEINT  and  DIS- 
ABLEINT  do  not  go  through  this  step  as  they  do  not  have  input  parameters.  How¬ 
ever,  all  the  routines  do  pop  into  the  HL  register  the  return  address  of  the  calling 
routine. 
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The  sixth  and  final  step,  common  to  all  nine  Utility  Module  routines,  is 
the  return  to  the  calling  PLZ  routine.  This  is  accomplished  simply  by  a  JP  (HL)  for 
jump  to  the  address  in  the  HL  register  instruction,  the  return  address  having  al¬ 
ready  been  popped  into  the  HL  register.  With  that  action,  the  Utility  Module  rou¬ 
tine  ends. 


PLZ  Activation  Record  (AREC)  for 
Utility  Module  Routine  ALLOCATE 


Output  Parameters 


Beginning_Address  — 


Ending_Address  - 


Available  Block  Size  * 


Return  Code 


Higher  Memory 


Stack  Pointer  +  0F  Hex 


Mark-Stack  Record 


Return  Address  - 


Calling  Routine's  IX 


R': 


s— i m 


Input  Parameters 


-  Block  Size  Requested 


-  Lower  Memory  Bound 


-  Upper  Memory  Bound 


STACK  POINTER 


Figure  32,  Example  of  PLZ  Activation  Record  —  ALLOCATE. 


Thus,  the  nine  assembly  language  routines  of  the  Utility  Module  give 
PLZ  language  routines  direct  access  to  input/output  port,  system  memory,  the 
system  date,  the  Z-80  interrupt  enable/disable,  and  the  RIO  operating  system 
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memory  management  routine.  The  following  pages  detail  the  nine  routines.  For 
each  routine  the  following  information  will  be  presented. 

1 .  The  name  of  the  routine. 

2.  The  name  of  the  routine's  module. 

3.  The  language  the  routine  is  written  in  and  the  number  of  lines  of 
code  in  the  routine. 

4.  A  synopsis  of  the  routine. 

5.  A  Routine  Relationship  Diagram  showing  the  relationship  of  the 
routine  to  the  PL Z  routines  that  call  it  and  the  elements  of  the  system 
that  it  calls. 

6.  The  invocation  statement  for  the  routine,  its  input  parameter  passing 
schema,  and  the  routines  called  by  the  routine. 

7.  A  description  of  the  global,  module,  and  local  level  constants  used 
by  the  routine. 

8.  Descriptions,  including  parameter  passing,  of  all  routines  called  by 
the  routine. 

9.  A  discussion  of  the  output  of  the  routine,  both  output  parameters  and 
effect  on  system  configuration. 

1 0.  The  testing  of  the  routine. 

11.  A  reference  to  the  pages  of  the  routine  code  listing. 


The  code  listing  of  the  routines  of  Utility  Module  are  in  Appendix  B. 
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1.  Name:  IOOUT 


2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language;  22  bytes. 


IOOUT  is  an  assembly  language  routine  which  gives  PLZ  language 
routines  direct  access  to  the  input/output  ports  of  the  system.  Through  IOOUT  a 
PLZ  program  can  write  directly  to  the  output  registers.  IOOUT  has  three  sections 
of  code,  AREC  save,  write  to  10  port,  and  return  to  calling  routine. 


Figure  33.  Relationship  of  IOOUT  to  Calling  PLZ  Routines  and  the 

Central  Processing  Unit 


a.  Invocation  Statement 

IOOUT  is  invoked  in  a  PLZ  routine  via: 
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IOOUT(  IO_PORT,  VALUE ) 


where  both  IO_PORT  and  VALUE  are  of  type  BYTE. 


b.  Input  Parameter  Passing  Schema 

IOOUT  has  two  input  parameters,  IO_PORT  and  VALUE,  both  of  type 
Byte.  IO_PORT  is  the  number  of  the  input/output  port  to  which  the  data  will  be 
output.  The  defined  rage  of  IO_PORT  is  0  to  255.  VALUE  is  the  quantity  to  be 
output  to  the  designated  IO_PORT. 


c.  Routines  Which  Call 

Though  IOOUT  call  be  called  by  any  PLZ  routine,  it  is  not  used  by  any 
of  the  final  software  in  this  thesis  effort. 


7.  Variables  and  Constants 

a.  Global 

IOOUT  uses  no  global  constants  or  variables  outside  the  defined  uses 
of  the  IX  and  HL  registers  for  subroutine  entry  /  exit. 


b.  Internal  to  the  Module 

IOOUT  uses  the  module  constant  ZERO,  value  0000  hex.  IOOUT 
uses  no  module  level  variables. 

c.  Internal  to  the  Routine 

None 


8.  Other  Routines  Called 

IOOUT  calls  no  other  routines. 
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The  output  of  IOOUT  is  the  writing  of  the  desired  VALUE  to  the  desired  j 

IO_PORT.  There  are  no  other  effects.  IOOUT  has  no  output  parameters.  \ 

i 

t 

i 

10.  Routine  Testing 

a.  Description  of  Test 

IO_OUT  was  tested  with  a  simple  PLZ  routine  which  writes  predeter¬ 
mined  values  to  predetermined  10  Ports.  The  ports  were  monitored  with  a  logic 
analyzer. 


b.  Results  of  Test 

The  desired  values  were  written  to  the  proper  ports.  Conclusion: 
IOOUT  works. 


11.  Reference  to  Listing 

The  listing  of  IOOUT  is  on  page  317  in  Appendix  B. 


Utility  Module 


131 


J, 


1 .  Routine  Name:  IOIN 

2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language;  25  bytes. 


IOIN  is  an  assembly  language  routine  which  gives  a  PLZ  language  routine 
direct  access  to  the  input/output  ports  of  the  system.  Through  IOIN  a  PLZ  pro¬ 
gram  can  directly  read  from  the  10  ports.  IOIN  has  three  subdivisions,  AREC 
save,  IO  port  read,  and  return  to  calling  routine. 


Any  PLZ  Language  Routine 


IOIN 


Address 


Data 


256  IO  Ports 


Z-80  CPU 


Figure  34.  Relationship  of  IOIN  to  Calling  PLZ  Routines  and  the 
Central  Processing  Unit. 


a.  Invocation  Statement 


IOIN  is  invoked  in  a  PLZ  routine  via: 


VALUE  :=  IOIN(  IO_PORT ) 
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where  both  IO_PORT  and  VALUE  are  of  type  BYTE. 

b.  Input  Parameter  Passing  Schema. 

IOIN  has  one  input  parameter,  IO_PORT,  the  number  of  the  input  /  out¬ 
put  port  dafe  is  to  be  read  from. 

c.  Routines  Which  Call  IOIN 

IOIN  can  be  called  by  any  PLZ  routine.  In  this  thesis  effort  IOIN  was 
not  used  in  the  final  software. 

7.  Variables  and  Constants 

a.  Global 

IOIN  uses  no  global  constants  or  variables  outside  the  defined  uses  of 
the  IX  and  HL  registers  for  subroutine  entry/exit. 

b.  Internal  to  the  Module 

The  module  constant  ZERO,  value  0000  hex,  is  used  by  IOIN;  there 
are  no  module  level  variables. 

c.  Internal  to  the  Routine 

None 

8.  Other  Routines  Called 

IOIN  calls  no  other  routines. 

9.  Output  of  Routine 

a.  Output  Parameter  Passing  Schema. 

IOIN  has  one  output  parameter,  VALUE  (type  Byte),  which  holds  the 
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data  read  in  from  the  10  port  indicated  by  the  input  parameter  IO_PORT. 


b.  System  Configuration  Changes 

Beyond  the  impact  of  the  read  upon  the  10  port's  status,  IOIN  causes 
no  system  changes. 


10.  Routine  Testing 

a.  Description  of  Test 

IOIN  was  tested  with  a  simple  PLZ  routine  which  read  (via  IOIN)  from  a 
serial  10  port  which  was  connected  to  a  terminal.  Characters  were  typed  in  at  the 
terminal.  The  characters  (VALUES)  read  were  then  displayed  to  the  system  con¬ 
sole. 


b.  Results  of  Test 

The  characters  typed  in  at  the  terminal  appeared  on  the  system  con¬ 
sole.  Conclusion:  JOIN  works. 


It  Reference  to  Listing 

The  program  listing  for  IOIN  is  located  on  page  318  in  Appendix  B. 
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1.  Name:  MEMSET 


2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language:  24  bytes. 


4.  Synopsis  of  Routine 

MEMSET  is  an  assembly  language  routine  which  permits  PLZ  lan¬ 
guage  routines  to  write  to  or  set  specific  random  access  memory  (RAM)  locations 
to  specific  values.  MEMSETs  code  has  three  major  subdivisions:  AREC  save, 
write  to  a  memory  location,  and  return  to  calling  routine. 


5.  Routine  Relationship  Diagram 


Any  PL Z  Language 


Figure  35.  Relationship  of  MEMSET  to  Calling  PLZ  Routines. 

6.  Invocation 

a.  Invocation  Statement 

MEMSET  is  invoked  in  a  PLZ  program  via: 

MEMSET(  LOCATION,  VALUE  ) 
where  LOCATION  is  type  Word  and  VALUE  is  type  byte. 
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b.  Input  Parameter  Passing  Schema 

MEMSET  has  two  input  parameters,  LOCATION  (type  Word),  the  ad¬ 
dress  of  specific  memory  location,  and  VALUE  (type  Byte),  the  quantity  to  be 
stored  in  the  location.  These  parameters  are  passed  via  standard  PLZ  methods. 


c.  Routines  Which  Call  MEMSET 

MEMSET  can  be  used  by  any  PLZ  routine  needing  direct  access  to 
memory  locations.  MEMSET  was  not  used  by  the  final  routines  of  this  thesis 
effort. 


7.  Variables  and  Constants 

a.  Global 

No  internal  module  variables  or  constants  besides  the  registers  used 
by  PLZ  subroutine  calls. 


b.  Internal  to  the  Module 

MEMSET  uses  the  constant  ZERO  of  value  0000  Hex;  no  module 
level  variables  are  used. 


c.  Internal  to  the  Routine 

MEMSET  uses  two  of  the  CPU  registers  to  hold  variables.  The  HL  reg¬ 
ister  holds  the  address  of  memory  location  to  be  read  and  the  A  register  holds  the 
value  read  from  memory  location.  No  routine  level  constants  are  used. 

8.  Other  Routines  Called 

MEMSET  calls  no  other  routines. 

9.  Output  of  Routine 

a.  Output  Parameter  Passing  Schema 
MEMSET  has  no  output  parameters. 


Utility  Module 


136 


b.  System  Configuration  Changes 


MEMSET  changes  the  quantity  stored  in  the  desired  memory  location 
to  the  specified  value. 


10.  Routine  Testing 

a.  Description  of  Test 

MEMSET  was  tested  by  having  a  simple  PL Z  routine  setting  specific 
memory  locations  to  know  values  via  MEMSET.  Then  the  debugger  was  used  to 
display  the  same  memory  locations. 


b.  Results  of  Test 

MEMSET  set  the  proper  memory  locations  to  the  proper  values.  Con¬ 
clusion:  MEMSET  works. 


11.  Reference  to  Listing 

The  program  listing  of  MEMSET  is  on  page  319  in  Appendix  B. 
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1.  Name:  MEMREAD 


2.  Part  of  Utility  Module 

3.  Written  in  2-80Assembly  Lanugage;  27  bytes. 


4.  Synopsis  of  Routine 

MEMREAD  is  an  assembly  language  routine  which  permits  PLZ  lan¬ 
guage  routines  to  read  specific  memory  locations,  RAM  OR  ROM.  MEMREAD 
has  three  major  subdivisions:  AREC  save,  read  of  memory  location,  return  to 
calling  routine. 


5.  Routine  Relationship  Diagram 


Any  PLZ  Language 
Routine 


\ Routine  / 

I  / 


Any  of  the 
64  K  RAM  and 
ROM  Memory  Locations 


L 


System  Memory 


I  I 


— FFFFh 
— C000h 
— 8000h 
— 4000h 
— 0000h 


Figure  36.  Relationship  of  MEMREAD  to  Calling  PLZ  Routines. 


6.  Invocation 

a.  Invocation  Statement 

MEMREAD  is  invoked  in  the  calling  PLZ  routine  via: 
VALUE  :=  MEMREAD(  LOCATION  ) 
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where  VALUE  is  of  type  Byte  and  LOCATION  is  of  type  Word. 


b.  Input  Parameter  Passing  Schema 

MEMREAD  has  one  input  parameter,  LOCATION  (type  Word),  the  ad¬ 
dress  of  specific  memory  location  to  be  read.  LOCATION  has  a  defined  range  of 
0  to  65535  decimal. 


c.  Routines  Which  Call  MEMREAD 

MEMREAD  was  not  used  by  any  of  the  final  data  collection  routines  of 
this  thesis  effort.  However,  it  can  be  used  by  any  PLZ  language  routine  needing 
direct  access  to  memory. 


a.  Global 


MEMREAD  uses  no  global  constants  or  variables. 


b.  Internal  to  the  Module 

Besides  the  registers  used  by  PLZ  subroutine  calls,  MEMREAD  uses 
no  module  level  variables.  The  module  constant  ZERO,  value  0000  hex,  is 
used  by  MEMREAD. 


c.  Internal  to  the  Routine 

MEMREAD  employs  two  CPU  registers  to  hold  variables.  The  HL 
register  holds  the  address  of  memory  location  to  be  read  and  the  A  register  holds 
the  value  read  from  memory  location.  There  are  no  routine  level  constants. 
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9.  Output  of  Routine 

a.  Output  Parameter  Passing  Schema 

MEMREAD  has  one  output  parameter,  VALUE,  which  is  the  quantity 
stored  in  the  memory  location  specified  by  the  input  parameter  LOCATION. 

b.  System  Configuration  Changes 

MEMREAD  causes  no  system  changes. 

10.  Routine  Testing 

a.  Description  of  Test 

MEMREAD  was  tested  by  setting  memory  locations  to  know  values 
with  the  debugger.  Then  a  simple  PLZ  routine,  which  reads  the  same  memory 
locations  (via  MEMREAD)  and  displays  them  on  the  console,  was  run. 

b.  Results  of  Test 

The  values  stored  in  the  memory  locations  were  properly  displayed. 
Conclusion:  MEMREAD  works. 

11.  Reference  to  Listing 

MEMREAD’s  program  listing  is  on  page  320  in  Appendix  B. 
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1.  Name:  DISABLEINT 


2.  Part  of  Utility  Module 


3.  Written  in  Z-80  Assembly  Language.  Three  bytes. 


DISABLEINT  is  a  very  simple  assembly  language  routine  which  enables  a 
PLZ  routine  to  disable  the  Z-80  interrupts.  This  routine  is  a  companion  to 
ENABLEINT. 


Figure  37.  Relationship  of  DISABLEINT  to  Calling  PLZ  Routines 
and  the  Interrupt  Setting  of  the  Central  Processing  Unit. 


a.  Invocation  Statement 


DISABLEINT  is  called  from  a  PLZ  program  via: 


DISABLEINT 
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b.  Parameter  Passing  Schema 
DISABLEINT  has  no  parameters. 

c.  Routines  Which  Call  DISABLEINT 

DISABLEINT  was  used  by  the  AIO.PLZ.S  Module  routines  which 
served  as  precursors  for  the  Sampler  Module  assembly  language  routines. 

7.  Variables  and  Constants 

The  only  "variable"  used  by  DISABLEINT  is  the  HL  register  which 
stores  the  address  of  the  calling  routine. 

8.  Other  Routines  Called 

DISABLEINT  calls  no  other  routines. 

9.  Output  of  Routine 

The  result  of  DISABLEINT  is  the  disabling  of  the  Z-80  interrupts. 

10.  Routing  Testing 

a.  Description  of  Test 

DISABLEINT  is  called  by  another  routine  which  causes  interrupts. 
With  that  routine  running,  a  logic  analyzer  was  used  to  monitor  the  CPU  lines. 


b.  Results  of  Test 

Before  the  invocation  of  DISABLEINT  the  CPU  responded  to  the 
interrupt  signals.  After  the  invocation  of  DISABLEINT  the  CPU  ignored  the 
interrupt  signals.  Conclusion:  DISABLEINT  works. 


11.  Reference  to  Listing 

The  program  listing  for  DISABLEINT  is  on  page  321  in  Appendix  B. 
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1.  Name:  ENABLEINT 


2.  Part  of  Utility  Module 

3.  Written  in  Z -80  Assembly  Language,  three  bytes. 

4.  Synopsis  of  Routine 

ENABLEINT  is  a  very  simple  assembly  language  routine  which  en¬ 
ables  a  PLZ  routine  to  enable  the  Z-80  interrupts.  ENABLEINT  is  a  companion  to 
routine  DISABLEINT. 


5.  Routine  Relationship  Diagram 


Figure  38.  Relationship  of  ENABLEINT  to  Calling  PLZ  Routines 
and  the  Interrupt  Setting  of  the  Central  Processing  Unit. 

6.  Invocation 


a.  Invocation  Statement 

ENABLEINT  is  invoked  from  the  calling  PLZ  routine  via: 


ENABLEINT. 
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b.  Parameter  Passing  Schema 


ENABLEINT  has  no  parameters. 


c.  Routines  Which  Call  ENABLEINT 

This  routine  was  not  used  by  any  of  the  final  version  routines  of  the 
data  collection  system.  However,  ENABLEINT  was  used  by  the  AI0.PL2.S 
Module  during  initial  software  design. 


7,  Variables  and  Constants 

The  only  "variable"  used  by  ENABLEINT  is  the  HL  register  which 
stores  the  address  of  the  calling  routine. 


8,  Other  Routines  Called 

ENABLEINT  calls  no  other  routines. 

i* 

9.,  Output  Qf  Routing 

The  result  of  ENABLEINT  is  the  enabling  of  the  Z-80  interrupts. 

10.  Routine  Testing 

a.  Description  of  Test 

ENABLEINT  is  called  by  another  routine  which  uses  interrupts.  With 
that  routine  running,  a  logic  analyzer  was  used  to  monitor  the  CPU  lines. 


b.  Results  of  Test 

Prior  to  the  invocation  of  ENABLEINT  the  CPU  ignored  the  interrupt 
signals;  afer  invocation,  the  interrupts  were  acknowledged.  Conclusion: 
ENABLEINT  works. 
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The  listing  of  ENABLEINT  is  on  page  322  in  Appendix  B. 


I 

» 

* 

i 

i 


' 


k 


i  t* 


\ 

> 


I 

I 

t 

t 

i 

I 


i 

i 


Utility  Module 


145 


1.  Routine  Name:  DATE 


2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language;  33  bytes. 


Procedure  DATE  is  an  assembly  language  routine  which  permits  a 
PLZ  language  routine  to  call  the  operating  system  an  obtain  the  current  system 
date.  DATE  has  four  major  subdivisions. 


First,  DATE  saves  the  IX  register  for  later  restoration. 

Second,  DATE  prepairs  pointers  to  both  the  stack  and  the  memory 
locations  where  the  date  is  stored. 


Third,  DATE  copies  the  six  characters  from  the  date  storage  locations  to 
the  stack. 


Fourth,  DATE  restores  the  IX  register,  gets  the  return  address,  and  returns 
control  to  the  calling  PLZ  routine. 


Figure  39.  Relationship  of  DATE  to  Calling  PLZ  Routines  and 
Memory  Locations  of  Date  Characters. 
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a.  Invocation  Statement 


DATE  is  invoked  in  the  calling  PL Z  routine  by: 

YEAR1 ,  YEAR0,  MONTH  1 ,  MONTH0,  DAY1 ,  DAY0  :=  DATE 
where  these  return  parameters  are  of  single  character  type. 


b.  Input  Parameter  Passing  Schema 

DATE  has  no  input  parameters;  it  uses  the  six  system  date  characters 
stored  in  memory  locations  1 3AB  -1 3C0. 


c.  Routines  Which  Call  DATE 

Any  PLZ  program  which  has  been  linked  with  the  Utility  Module  can 
call  DATE.  For  this  thesis  effort,  DATE  is  called  by  GET_DATE  of  the 
Collect  Data  Module. 


7,  Variables  and  C,Qn?ta?3ls 

a.  Global  Constants 

ZERO:  0000  Hex,  just  a  constant  for  zero 

DATE_ADDRESS:  1 3AB  Hex,  the  first  of  six  system  date  memory 

locations 


b.  Variables  Internal  to  the  Module 

Named  module  variables  per  say  are  not  used,  however,  some  regis¬ 
ters  of  the  Z-80  are  used  by  the  subroutine  call  schema.  The  return  address  is  on 
the  top  of  the  stack  at  the  onset  of  the  called  subroutine.  The  IX  register  is  used 
by  PLZ  to  point  to  the  Activation  Record  (AREC),  a  table  of  pointers  created  for 
subroutine  calls.  Thus,  it  is  important  to  save  and  restore  the  IX  register. 


c.  Variables  Internal  to  the  Routine 

Though  no  named  variables  are  used,  several  of  the  Z-80  CPU  regis- 
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ters  are  used  to  hold  variables.  The  C  register  is  used  to  count  down  the  6  chara¬ 
cter-transfers.  The  HL  register  points  to  the  system  date  storage  location  for  each 
character.  The  DE  register  points  to  the  output  storage  location  for  each  chara¬ 
cter,  the  destination  location. 


8.  Routines  Called  bv  DATE 

DATE  calls  no  other  routines. 


9.  Output  of  Routine 

a.  Output  Parameter  Passing  Schema 

DATE  outputs  six  parameters,  the  six  ASCII  characters  of  the  system 
date.  These  six  parameters,  YEAR1,  YEAR0,  MONTH1,  MONTH0,  DAY1,  and 
DAY0,  are  all  of  type  Byte. 


b.  System  Configuration  Changes 

DATE  does  not  modify  any  system  configurations. 


Ranting  Testing 

a.  Description  of  Test 

DATE  was  tested  by  loading  the  system  date  (via  RIO  routine  DATE 
with  known  values  and  then  running  a  simple  PL Z  routine  which  called  DATE 
and  output  the  returned  values  to  the  screen. 


b.  Results  of  Test 

It  worked  properly. 


11.  Reference  to  Listing 

The  listing  of  DATE  can  be  found  on  page  323  in  Appendix  B. 
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1.  Name:  ALLOCATE 


2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language;  82  bytes. 

4.  Synopsis  of  Routine 

ALLOCATE  is  an  assembly  language  routine  which  permits  PLZ 
language  routines  access  to  the  system  memory  manager.  The  specific  purpose 
of  ALLOCATE  is  memory  allocation;  DEALLOCATE  is  a  companion  routine. 
ALLOCATE  has  seven  subdivisions. 

a.  AREC  save 

b.  Load  of  input  parameters  into  Registers  for  OS  call. 

c.  Call  to  memory  manager  to  allocate  memory. 

d.  Load  of  two  OS  response  parameters  into  subroutine  return 
locations. 

e.  Error  Code  evaluation. 

f.  Load  of  remaining  OS  response  parameters  into  subroutine  return 
locations. 

g.  Return  to  calling  routine. 

5.  Routine  Relationship  Diagram 


Any  PLZ  Language  Routine 


\ 


ALLOCATE 


Memory  Manager 


^w»RIO  Operating  System 


System  Memory 


■ 0000h 


Figure  40.  Relationship  of  ALLOCATE  to  Calling  PLZ  Routines  and 
the  RIO  Operating  System. 
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a.  Invocation  Statement 


ALLOCATE  is  invoked  in  a  PLZ  program  as  follows. 

RETURN_CODE,  AVAILABLE_BLOCK  SIZE, 

BEGINNING_ADDRESS,  ENDING_ADDRESS  := 

ALLOCATE(  BLOCK_SIZE_REQUESTED, 
LOWER_MEMORY_BOUND, 
UPPER_MEMORY_BOUND  ) 

where  RETURN_CODE  is  type  Byte,  and  the  remaining  parameters  are  type 
Word. 


b.  Input  Parameter  Passing  Schema 

ALLOCATE  uses  three  input  parameters  and  follows  the  standard 
subroutine  parameter  passing  methods.  The  input  parameters  are: 

BLOCK_SIZE_REQUESTED:  This  is  the  size  of  memory  block,  in  bytes,  for 

which  memory  allocation  is  being  requested. 
As  this  is  is  of  type  Word,  its  defined  range  is  0 
to  65,536  (64K).  Type  Word. 

LOWER_MEMORY_BOUND:  The  memory  location  that  allocation  must  be 

above.  Defined  range  0  to  64K.  This  para¬ 
meter  is  used  to  fence  out  areas  of  memory  for 
other  use.  Type  Word. 

UPPER_MEMORY_BOUND:  The  memory  location  that  the  allocation  must  be 

below.  Defined  range  0  to  64K.  This  para¬ 
meter  is  used  to  fence  out  areas  of  memory. 
Type  Word. 


c.  Routines  Which  Call  ALLOCATE 

The  current  versions  of  the  data  collection  software  do  not  use  ALLO¬ 
CATE.  However,  ALLOCATE  would  be  used  by  an  improved  SIZE_DAT_BUF- 
FER  (Collect_  Data  Module)  to  provide  direct  access  to  the  RIO  Operating  System 
Memory  Manager. 
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a.  Global 


There  are  no  true  global  variables  or  constants  used  by  ALLOCATE. 


b.  Constants  Internal  to  the  Module 


ZERO: 

ALCT_MEMORY: 
MEMORY_MANAGER: 
OPERATION  COMPLETE: 


0000  Hex 

00  Hex,  the  code  for  allocate  memory  passed 
to  the  memory  manager. 

1409  Hex,  the  address  of  the  memory  manager 
entry  point. 

80  Hex,  the  return  code  for  successful  memory 
allocation. 


c.  Internal  to  the  Routine 

Besides  the  use  of  the  CPU  registers  to  hold  parameters  (see  below), 
ALLOCATE  has  no  internal  constants  or  variables. 


8.  Other  Routines  Called 

ALLOCATE  calls  the  RIO  Operating  System  Memory  Manager.  The 
CPU  registers  are  used  to  pass  parameters  between  ALLOCATE  and  the  Mem¬ 
ory  Manager.  For  the  call  to  the  Memory  Manager: 

BC  holds  the  BLOCK_SIZE_REQUESTED  in  bytes: 

HL  holds  the  LOWER_MEMORY_BOUND  address; 

DE  holds  the  UPPER_MEMORY_BOUND  address; 

A  holds  the  request  code  for  memory  allocation,  00  hex. 

The  Memory  Manager  returns: 

BC  holds  the  AVAILABLE_BLOCK_SIZE  (which  may  be  that 
requested); 

HL  holds  the  BEGINN1NG_ADDRESS  of  the  allocated  or  available 
block; 

DE  holds  the  ENDING_ADDRESS  of  the  allocated  or  available  block; 
A  holds  the  RETURN_CODE. 

The  values  placed  in  the  registers  and  returned  by  the  memory  manager  are 
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functionally  the  same  as  the  input  and  output  parameters  of  ALLOCATE. 


a.  Output  Parameter  Passing  Schema 

The  four  parameters  returned  by  ALLOCATE  to  the  calling  PLZ  routine 


RETURN_CODE:  Type  Byte.  The  return  code  is  the  operating  system's 

message  on  its  success  in  allocating  the  desired  block 
of  memory.  If  a  block  of  memory  was  successfully  allo¬ 
cated  the  RETURN_  CODE  will  be  zero.  On  the  other 
hand,  if  a  contiguous  block  of  the  desired  size  could  not 
be  found,  RETURN_CODE  will  have  the  value  4A  hex 
which  means  insufficient  memory. 

AVAILABLE_BLOCK_SIZE:  Type  Word.  The  value  returned  in  this  parameter 

depends  upon  whether  the  BLOCK_SIZE_REQUES- 
TED  was  available.  If  it  was,  then  AVAILABLE_ 
BLOCKJ3IZE  is  the  number  of  bytes  requested.  If 
however  the  BLOCK_SIZE_REQUESTED  was  not 
available,  AVAILABLE_BLOCK_SIZE  will  be  the  num¬ 
ber  of  bytes  of  the  largest  available  block  in  system 
memory. 

BEGINNING_ADDRESS:  Type  Word.  This  parameter  has  three  possible  values. 

If  memory  is  successfully  allocated,  BEGINNING_AD- 
DRESS  will  be  the  memory  address  of  the  beginning  of 
the  allocated  block.  If  sufficient  memory  is  not  avail¬ 
able,  BEGINNING_ADDRESS  will  be  the  memory  ad¬ 
dress  of  the  beginning  of  the  largest  block  of  memory 
that  is  available.  If  not  even  one  single  byte  of  memory 
is  available,  BEGINNING_ADDRESS  will  be  zero. 


ENDING  ADDRESS: 


Type  Word.  This  parameter  has  two  possible  values.  If 
memory  allocation  was  successful,  ENDING_AD- 
DRESS  will  be  the  memory  address  of  the  allocated 
block.  If  there  was  insufficient  memory  for  the  BLOCK_ 
SIZE  REQUESTED  then  ENDING  ADDRESS  will  be 
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b.  System  Configuration  Changes 

If  memory  allocation  was  successful,  the  Operating  system  will  have 
the  requested  block  of  memory  reserved.  If  allocation  was  not  successful,  no 
system  configuration  changes  will  have  occured. 


10.  Routine  Testing 

a.  Description  of  Test 

A  simple  PLZ  program  which  calls  the  memory  manager  via  allocated 
was  written.  This  program  outputs  to  the  console  the  return  code  from  the  call  to 
the  memory  manager  and  the  other  output  parameters  of  AOLLCATE.  The  pro¬ 
gram  was  run  a  number  of  times  with  different  input  parameters.  Between  runs, 
the  operating  system  memory  status  display  was  displayed  to  see  the  current 
memory  allocation.  DEALLOCATE  was  tested  concurrently. 


b.  Results  of  Test 

When  the  request  was  valid,  ALLOCATE  successfully  conveyed  the 
requests  to  the  memory  manager;  memory  was  allocated.  When  unsatisfiable 
requests  were  made,  ALLOCATE  received  and  correctly  interperted  the  respon¬ 
ses  from  the  memory  manager.  Conclusion:  ALLOCATE  works. 


U.  .Rsferaagg  tQ  Listing 

The  program  listing  for  ALLOCATE  is  on  pages  324  -  325  in  Appendix 
B. 
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1.  Name:  DEALLOCATE 


2.  Part  of  Utility  Module 

3.  Written  in  Z-80  Assembly  Language;  38  bytes. 


DEALLOCATE  is  an  assembly  language  routine  which  permits  a  PLZ 
program  access  to  the  operating  system  memory  manager  for  deallocation  of 
specific  blocks  of  memory.  DEALLOCATE  has  four  major  sections  of  code: 

a.  ARECsave 

b.  Call  of  Memory  Manager 

c.  Output  Parameter  setup 

d.  Stack  clean  up  and  return  to  calling  routine. 


Any  PLZ  Language  Routine 

\  I  /  System  Memory 


DEALLOCATE 


■FFFFh 


■C000h 


Memory  Manager  | 


■8000h 
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•RIO  Operating  System  < 


•0000h 


Figure  41 .  Relations  of  DEALOCATE  to  Calling  PLZ  Routines  and 
to  RIO  Operating  System. 
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a.  Invocation  Statement 


DEALLOCATE  is  invoked  in  a  PLZ  routine  via: 

RETURN_CODE  :=  DEALLOCATE(  BLOCK_SIZE,  BEGINNING.  ADDRESS) 

where  RETURN_CODE  is  of  type  Byte  and  BLOCK_SIZE  and  BEGINNING_AD- 
DRESS  are  of  type  Word.  The  Utility  Module  must  be  linked  in  will  the  calling 
program. 


b.  Input  Parameter  Passing  Schema 

DEALLOCATE  has  two  input  parameters,  BLOCK_SIZE  and  BEGIN- 
NING_  ADDRESS.  BLOCK_SIZE  is  the  number  of  memory  locations  to  be  de¬ 
allocated.  BEGINNING_ADDRESS  is  the  address  of  the  first  memory  location  of 
the  block  to  be  deallocated.  The  block  to  be  deallocated  must  be  fully  allocated 
at  the  onset  of  this  routine. 


c.  Routines  Which  Call 

DEALLOCATE  can  be  called  by  any  PLZ  program  linked  with  the 
Utility  Module.  Though  it  is  not  used  in  any  of  the  current  data  collection  software. 
An  improved  SIZE_DATA_BUFFER  that  uses  ALLOCATE  would  force  the  use  of 
DEALLOCATE  near  the  end  of  module  execution  to  free  up  memory. 


7„  variates  and  Constants 

a.  Global 

There  are  no  true  global  variables  or  constants. 


b.  Constants  Internal  to  the  Module 
ZERO:  00  hex 

DEALCT_MEMORY:  01  Hex,  the  code  for  deallocation  of  memory 

passed  to  the  memory  manager. 
MEMORY_MANAGER:  1 409  Hex,  the  address  of  the  memory 

manager  entry  point. 
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c.  Internal  to  the  Routine 


Besides  the  CPU  registers  used  to  hold  parameters  (see  below),  DE¬ 
ALLOCATE  has  no  internal  variables  or  constants. 


8.  Other  Routines  Called 

DEALLOCATE  uses  the  system  Memory  Manager  routine.  CPU  regis¬ 
ters  are  used  to  pass  parameters  between  DEALLOCATE  and  the  Memory  Man¬ 
ager.  When  DEALLOCATE  calles  memory  manager: 

BC  holds  the  BLOCK_SIZE  to  be  deallocated; 

HL  holds  the  BEGINNING_ADDRESS  of  the  block; 

A  holds  the  request  code  for  memory  deallocation,  01  hex. 

The  Memory  Manager  returns  to  DEALLOCATE  register  A  holding  the  RETURN_ 
CODE,  80  hex  for  successful  deallocation  or  43  hex  for  memory  protect  violation. 
Memory  protect  violation  occurs  when  the  block  identified  for  deallocation  is  not 
completely  and  continuously  allocated.  Note  that  these  register  stored  values  are 
the  input  and  output  parameters  of  DEALLOCATE. 


9*  Qu.tpulQfJBQ.ulma 

a.  Output  Parameter  Passing  Schema 

DEALLOCATE  returns  a  single  parameter,  RETURN_CODE,  which 
indicates  whether  the  deallocation  was  successful.  If  the  deallocation  was  suc¬ 
cessful,  RETURN_  CODE  will  have  a  value  of  80  hex.  If  the  deallocation  is  un¬ 
successful  the  RETURN  CODE  will  have  a  value  of  43  hex. 


b.  System  Configuration  Changes 

If  memory  deallocation  was  successful,  the  block  of  memory  specified 
by  the  input  parameters  will  no  longer  be  allocated.  If  deallocation  was  unsuc¬ 
cessful,  no  configuration  changes  will  have  occured. 
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a.  Description  of  Test 

DEALLOCATE  was  tested  in  conjunction  with  ALLOCATE  through  a 
simple  PL Z  routine.  This  routine  used  ALLOCATE  and  DEALLOCATE  to  alter  the 
system  memory  allocation.  In  between  calls,  the  status  of  the  system  memory 
was  checked  via  an  operating  system  utility. 


b.  Results  of  Test 

Whenever  the  deallocation  request  was  valid,  DEALLOCATE  suc¬ 
cessfully  deallocated  the  specified  block  of  memory  and  returned  the  successful 
operation  return  code.  When  invalid  deallocation  requests  were  made,  DEALLO¬ 
CATE  was  unable  to  deallocate  memory  (as  it  shouldn't)  and  returned  the  proper 
return  code  for  memory  protect  violation.  Conclusion:  DEALLOCATE  works. 


11.  Reference  to  Listing 

DEALLOCATES  listing  can  be  found  on  pages  326  -  327  in  Appendix 
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Introduction  to  Sampler  Module 

The  Sampler  Module  is  a  collection  of  twelve  assembly  language 
routines  which  implement  a  real-time  clock  paced  data  collection  system.  The 
module  uses  periodic  interrupts  from  the  CTC  (counter/timer  chip)  of  the  MCB 
Board  to  initiate  analog  to  digital  conversions  by  the  AIO  (analog  input  output) 
board.  When  each  conversion  is  complete,  the  digital  data  is  read  from  the  AIO 
board  and  placed  in  a  buffer.  The  process  continues  until  a  specified  number  of 
samples  has  been  input  and  stored  in  the  buffer.  This  interrupt  /  convert  /  store 
process  is  preceeded  by  a  series  of  initilization  steps  and  is  followed  by  a  set  of 
shut  down  and  deallocation  routines. 

In  the  following  paragraphs,  the  organization,  program  flow,  interrupt 
routine  selection,  invocation,  language,  calf  overhead,  testing,  and  known  pro¬ 
blems  of  Sampler  Module  are  discussed.  Following  these  discussions  are  the 
detailed  descriptions  of  the  twelve  routines  of  the  module. 


Organization  and  Function  of  Sampler  Module  Routines 

Sampler  Module  is  organized  into  an  executive  rouine,  nine  subor¬ 
dinate  routines,  and  two  interrupt  service  routines.  Sampler  Module  could  have 
been  written  as  a  single  sequence  of  assembly  cods  plus  the  two  interrupt  ser¬ 
vice  routines.  This  approach  was  rejected  in  favor  of  the  executive  /  subordinate 
organization  for  three  reasons.  First,  the  executive/subordinate  structure  is  far 
more  readable  and  maintainable  than  a  long  single  string  of  code.  The  executive 
clearly  shows  the  high  level  program  flow  and  all  the  module  control  branching; 
this  detail  would  have  been  obscured  in  a  large  single  string  of  code.  Second,  a 
number  of  the  subordinate  routines  are  complete  functions  developed  originally 
in  PLZ  (AIO.PLZ.S  Module)  or  used  elsewhere;  these  routines  were  already  func¬ 
tionally  separate  routines.  Third,  the  functions  needed  in  the  module  logically 
follow  a  building  block  organization,  particularly  the  interrupt  service  routines. 
For  these  reasons,  Sampler  Module  is  organized  into  an  executive  routine,  nine 
subordinate  routines,  and  two  interrupt  service  routines. 


The  twelve  routines  of  Sampler  Module  and  and  a  description  of  their 
their  functions  fpllows. 
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SAMPLER 


Executive  routine  of  Samper  Module.  Calls  routines 
VALIDATE  through  DEALLOCATE  in  turn. 

VALIDATE  Verifies  the  correctness  of  the  module  input  parameters. 

ATODINIT  Initializes  the  AIO  Board  by  putting  the  board  Into  polled 

mode  and  clears  the  analog  to  digital  input  registers. 

CTCJPROGRAM  Initializes  the  CTC  timer  chip  by  loading  the  desired 

prescaller  for  the  timing  count  and  the  interrupt  vector. 

!NT_SET_UP  Establishes  the  parameters  for  the  interrupt  service 

routine  including  selection  of  TO_SAMPLE  or 
TC_SAMPLE  for  the  interrupt  service  routine. 

INIT_COLLECTOR  Loads  control  parameters  in  to  the  CPU  registers. 

USER_READY?  Querries  the  user  via  the  system  console  and  keyboard  for 

a  signal  to  begin  data  collection. 

STARTJTIMER  Loads  the  CTC  timer  with  the  selected  time  constant 

which  complets  its  programming  and  initiates  the  real  time 
clock. 

COLLECTER  Loops,  polling  the  AIO  board  status  register  and  reads  In 

converted  data  when  an  analog  to  digital  conversion  is 
complete.  Counts  the  collections  and  ends,  exiting  loop, 
when  last  sample  has  been  read. 

CTC_OFF  Deactivates  the  interrupts  and  timing  of  the  CTC. 

DEALLOCATE  Loads  the  output  parameters  and  deallocates  stack  space 

of  the  input  parameters. 

TO_SAMPLER  Interrupt  service  routine  for  sample  periods  of  0.01 

seconds  or  less.  No  counter  is  used.  Initiates  an  analog 
to  digital  conversion  each  time  called. 

TC_SAMPLER  Interrupt  service  routine  for  sample  periods  greater  than 

0.01  seconds.  Decrements  a  counter  each  time  called. 
When  counter  reaches  zero,  initiates  an  analog  to  digital 
conversion  and  resets  the  counter. 
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The  flow  of  program  execution  between  the  executive  routine  SAM¬ 
PLER  and  its  nine  subordinate  routines  is  shown  by  Figure  42  below.  SAMPLER 
calls  its  nine  subordinate  routines  in  succession  with  two  possible  branches. 
These  branchs  occur  within  SAMPLER  and  are  based  on  the  output  (state  of  the 
CPU  zero  flag)  of  subordinate  routines  VALIDATE  and  USER_READY?.  In  both 
cases  the  branching  is  to  abort  the  execution  of  the  remaining  module  steps. 
From  VALIDATE,  Sampler  Module  execution  is  aborted  if  the  input  parameters 
supplied  by  the  calling  PLZ  program  are  invalid.  From  USER_READY?  execu¬ 
tion  is  aborted  if  the  User  signals  to  abort  data  collection.  Abortion  of  execution 
from  USER_READY?  requires  a  call  to  CTC_OFF  to  disable  CTC  timing  and 
interruptions.  DEALLOCATE  is  called  from  both  execution  abortion  paths  to  pre¬ 
pare  for  the  return  to  the  calling  PLZ  routine.  For  more  information  on  the  internal 
execution  and  interfaces  of  the  Sampler  Module  routines,  please  consult  the  de¬ 
tailed  routine  descriptions. 

The  interrupt  service  routine,  either  TO_SAMPLE  and  TC_SAMPLE,  is 
not  called  by  SAMPLER.  Instead,  the  interrupt  service  routine  executes  out  of 
routine  COLLECTER.  INT_SET_UP  selects  which  interrupt  service  routine  will 
be  used  and  loads  the  address  of  the  selected  routine  into  the  interrupt  vector 
location.  When  a  CTC  issued  interrupt  occurs,  program  execution  jumps  to  the 
selected  interrupt  service  routine.  When  interrupts  are  not  being  serviced,  the 
code  of  COLLECTER  is  being  executed.  The  logic  states  of  COLLECTER,  in¬ 
cluding  the  jumps  to  the  interrupt  service  routine,  are  shown  in  Figure  43  below. 
COLLECTER  primarly  sits  in  READY?  checking  whether  an  analog  to  digital  con¬ 
version  has  been  completed  and  data  is  ready.  It  is  during  this  READY?  state 
that  interrupts  will  occur.  The  interrupt  service  routine,  either  TO_SAMPLE  or 
TC_SAMPLE,  initiates  the  analog  to  digital  conversion.  When  data  is  ready  from 
the  AIO  board,  COLLECTER  shifts  to  the  DATA_READY  state.  There,  COL¬ 
LECTER  reads  in  and  stores  the  data.  COLLECTER  then  checks  to  see  how 
many  samples  have  been  read  in.  If  there  are  more  samples  to  be  collected, 
execution  shifts  back  to  state  READY?.  If  all  the  samples  have  been  collected, 
execution  shifts  to  the  FINISHED  state.  FINISHED  corrects  all  pointers  and 
returns  program  execution  to  SAMPLER. 


Interrupt  Routine  Selection 

Which  interrupt  service  routine  is  used  depends  upon  the  sampling 
period  required.  The  CTC  timer  alone  can  generate  periodic  interrupts  every 
6.515  microseconds  to  26.58  miliseconds  (Ref  7:  Sec  3.7).  The  interval  between 
the  interrupts  is  determined  by  the  prescale  factor  (16  or  256)  and  the  time  con¬ 
stant  given  to  the  CTC  during  programming.  For  sampling  periods  within  the 
above  range,  the  interrupt  service  routine  simply  writes  to  the  AIO  channel  select 
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register  each  time  an  interrupt  occurs.  This  is  the  procedure  used  by  TO_SAM 
PLER,  the  "TO"  standing  for  "Timer  Only." 


Calling  PLZ  Routine 
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Input 

Parameters 


User 

Aborts 
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Figure  43.  Operation  States  During  Subordinate  Routine  COLLECTER  Including 

the  Interrupt  Service  Routine. 


To  obtain  longer  sampling  periods,  a  counter  must  be  added  to  the 
interrupt  service  routine.  Each  time  the  CTC  issues  an  interrupt,  the  interrupt 
service  routine  decrements  a  counter.  When  the  counter  reaches  zero,  the 
service  routine  writes  to  the  AIO  channel  select  register  and  resets  the  counter. 
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For  this  method  of  generating  sampling  periods,  three  parameters  are  required, 
the  CTC  prescale  factor,  the  CTC  time  constant,  and  the  counter  value.  This 
method  is  used  by  TC_SAMPLER,  where  "TC"  stands  for  "Timer  &  Counter." 
Given  a  sixteen  bit  counter  in  addition  to  the  CTC  timer,  sampling  periods  of 
1.688  miliseconds  to  29.3  minutes  are  possible  with  the  timer  and  counter 
combination. 

Figure  44  below  shows  the  sampling  period  ranges  of  the  various 
combinations  of  CTC  timers  and  sixteen  bit  counters.  Slow  Timer  refers  to  a  CTC 
timer  using  a  prescale  factor  of  256.  Fast  Timer  refers  to  a  CTC  timer  using  a 
prescale  factor  of  16.  As  shown  in  the  figure,  the  sampling  period  ranges  of  the 
timers  and  the  timer/counter  combinations  overlap. 

For  this  thesis  effort,  aribritrary  break  points  to  choose  between  the 
four  different  timing  methods  were  selected.  For  sample  periods  below  0.01 
seconds,  the  CTC  timer  only  (interrupt  service  routine  TO_SAMPLE)  is  used.  For 
periods  less  than  0.001  seconds  a  prescale  factor  of  16  is  loaded  into  the  CTC; 
for  periods  0.001  seconds  to  0.01  seconds  ,  the  prescale  factor  is  256.  The 
timer  counter  combination  (interrupt  service  routine  TC_SAMPLE)  is  used  for 
sampling  periods  0.01  seconds  and  above.  For  periods  from  0.01  seconds  up 
to  1.0  second,  a  fast  timer  (prescale  factor  of  16)  is  used  with  the  16  bit  counter. 
For  periods  from  1.0  second  to  the  maximum  time  possible  of  29.3  minutes,  the 
slow  timer  (prescale  of  256)  is  used.  The  shaded  areas  on  Figure  44  show  the 
employed  ranges  for  each  timer/counter  combination. 

The  parameters  which  program  the  CTC  and  the  sixteen  bit  timer  are 
input  parameters  to  Sampler  Module.  The  calling  PL Z  routine  establishes  these 
values  based  on  the  user's  desired  sampling  period  and  the  routine  break  points 
discussed  above.  Routine  INT_SET_UP  looks  at  the  input  parameter  COUNT, 
the  sixteen  bit  down  counter  value.  If  COUNT  is  zero,  INT_SET_UP  selectes 
TO_SAMPLE  as  the  interrupt  service  routine.  If  COUNT  is  nonzero,  TC_SAMPLE 
is  used.  Please  note  that  the  calling  PLZ  routine  does  not  use  the  full  range  of 
the  fast  timer  only  combination.  To  allow  sufficient  time  for  the  analog  to  digital 
conversion  to  take  place,  the  shortest  sampling  period  actually  employed  is  50.0 
microseconds. 


Invocation  of  Sampler  Module 

As  shown  by  Figure  42  above,  Sampler  Module  is  called  from  a  PLZ 
program.  The  PLZ  program  supplies  the  three  values  needed  to  program  the  real 
time  clock  ,  specifies  how  many  samples  are  to  be  collected,  and  names  the 
analog  input  channel  is  to  be  used.  The  executive  routine  SAMPLER  is  the 
program  interface  between  the  calling  PLZ  routine  and  all  of  Sampler  Module. 
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SAMPLER,  and  hence  all  of  Sampler  Module,  is  invoked  from  a  PLZ  routine  with 

ERROR_CODE,  LAST_DATA  := 

SAMPLER(  IO_CHANNEL,  CTC_MODE, 
TIME_CNST,  COUNT, 
NUM_SAMPLES,  FIRST_DATA  ) 

The  purpose  and  type  of  the  input  and  output  parameters  is: 


IO_CHANNEL  Byte  Selects  which  one  of  the  1 6  possible  AIO 

board  analog  input  channels  is  to  be  used. 
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CTC_MODE 

Byte 

Passes  the  first  half  of  the  command  used  tc 
program  the  CTC  to  issue  interrupts  at  the 
desired  rate. 

TIME_CNST 

Byte 

Passes  the  second  half  of  the  CTC 
programming  command. 

COUNT 

Word 

The  number  of  CTC  interrupts  required 
between  data  collections.  This  parameter  is 
used  only  for  long  timer  periods. 

NUM_SAMPLES 

Word 

The  number  of  data  samples  to  be  read  in. 

FIRST_DATA 

Pointer- 

to-Byte 

A  pointer  to  the  first  memory  location  for  the 
stroage  of  the  data  read  in. 

LAST_DATA 

Pointer- 

to-Byte 

Outputs  the  pointer  to  the  last  memory 
location  that  data  was  stored  in. 

ERROR_CODE 

Byte 

Passes  back  to  the  calling  routine  an  error 
message  if  the  calling  routine's  inputs  were 
improper. 

Although  the  executive  routine  SAMPLER  is  the  sole  program  exe¬ 
cution  interface  to  the  calling  PLZ  routine,  SAMPLER  does  not  use  any  of  the 
subroutine  call  parameters.  Instead,  the  input  and  output  parameters  are  em¬ 
ployed  only  by  the  subordinate  routines  which  need  them.  From  the  calling  PLZ 
routine's  perspective,  Sampler  Module  is  simply  a  single  subroutine;  the  exe¬ 
cutive/subordinate  organization  of  these  assembly  language  routines  is  neither 
visible  nor  important. 


Selection  of  Assembly  Language  for  Sampler  Module 

The  routines  of  Sampler  Module  were  written  in  assembly  language 
primarly  to  gain  a  speed  of  execution  advantage.  Given  the  access  to  the  system 
provided  by  the  Utility  Module  routines,  Sampler  Module  could  have  been  written 
in  PLZ.  In  fact,  some  of  the  PLZ  language  routines  of  the  AIO.PLZ.S  Module  are 
precursors  of  some  of  the  assembly  language  routines  in  Sampler  Module.  The 
only  problem  with  PLZ  is  speed.  The  overhead  required  by  a  PLZ  routine  would 
have  precluded  the  shorter  sampling  periods  achieved  by  using  assembly 
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language  routines.  With  PLZ  and  the  Utility  Module  routines,  the  polling  of  the 
AIO  status  register  would  have  required  a  PLZ  call  to  IOIN,  execution  of  IOIN  (1 1 
instructions),  and  the  return  to  the  PLZ  routine.  This  sequence  would  have 
required  approximately  200  microseconds  to  execute  (see  Appendix  C).  With 
assembly  language  the  whole  loop  is  just  four  instructions  requiring  about  16 
microseconds  to  execute.  Another  example  is  the  calculation  of  the  CTC  timer 
and  sixteen  bit  counter  values  for  the  sampling  period.  These  could  have  been 
done  in  assembly  language  with  ihe  addition  of  some  math  utilities.  However,  in 
PLZ  the  math  and  high  level  logical  branching  instructions  were  already  present. 
By  having  the  assembly  language  Sampler  Module  interface  with  a  PLZ  parent 
routine  the  best  of  both  worlds  was  obtained,  the  speed  and  direct  hardware 
access  of  assembly  language  coupled  with  the  higher  level  programming  of  PLZ. 


Overhead  for  PLZ  Subroutine  CalLof  Sampler  Module 

The  overhead  for  an  assembly  language  routine  to  be  called  by  a  PLZ 
routine  was  extensively  discussed  in  the  introduction  to  the  Utility  Module.  Rather 
than  repeate  that  discussion  here,  please  refer  to  the  Utility  Module  discussion 
and  sample  AREC  for  more  information  of  PLZ  parameter  passing  schema.  The 
figure  below  shows  the  PLZ  Activation  Record  (AREC)  for  the  parent  routine's  call 
of  Sampler  Module. 


External  Calls  Q.f  the-Samplec-MQduig 

The  routines  of  Sampler  Module  use  no  other  subroutines.  However 
the  RIO  Operating  System  and  several  hardware  elements  of  the  MCB  develop¬ 
ment  system  are  called.  The  items  called,  the  calling  routine,  and  the  purpose  of 
the  calls  are  fully  detailed  in  the  routine  descriptions. 


Testing  of  Sampler  Module 

Three  types  of  tests  were  performed  on  the  routines  of  Sampler 
Module.  First,  one  of  the  routines,  ATODINIT,  was  individually  tested.  Second, 
portions  of  Sampler  Module  were  tested  using  the  RIO  debugger.  Third,  a  short 
PLZ  module  was  written  solely  to  call  and  test  Sampler  Module.  ATODINIT  was 
an  established  routine  which  functioned  properly.  Its  individual  testing  was  its 
prior  use.  The  rest  of  the  testing  was  far  more  involved. 

The  testing  with  the  debugging  routine  was  limited  in  application  and 
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PLZ  Activation  Record  (AREC) 
for  Sampler  Module 
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Figure  45.  Activation  Record  for  Call  of  Sampler  Module. 


somewhat  cumbersome  to  accomplish.  The  debugging  routine  is  interrupt  dri¬ 
ven;  Sampler  Module  is  interrupt  driven.  Thus,  the  debugger  could  not  be  readily 
used  to  test  the  interrupting  portion  of  Sampler  Module.  The  debugger  was  used 
in  conjunction  with  a  logic  analyzer  to  examine  the  Sampler  Module  routines 
which  set  the  Z-80  registers  and  worked  with  the  AIO  board.  The  CTC  related 
routines  which  delt  with  interrupts  were  not  tested  with  the  debugger.  The  logic 
analyzer  was  used  to  trap  the  input/output  port  calls.  One  of  the  more  difficult 
actions  was  to  manually  insert  the  parameters  that  a  calling  PLZ  would  normaly 
have  placed  in  the  system  stack.  This  action  was  aided  by  the  symbolic  capa¬ 
bilities  of  debugger  which  allowed  access  by  name  rather  than  hexidecimal 
addressses.  The  debugger  testing  showed  that  the  tested  protions  were  func- 
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tioning  properly.  The  AIO  board  was  receiving  the  proper  commands  and  infor¬ 
mation  could  be  obtained  from  it. 

Things  didn't  go  as  well  with  the  PL Z  routine  testing.  For  this  test,  a 
short  PLZ  routine  was  written  for  the  sole  purpose  of  calling  Sampler  Module. 
The  routine  consisted  of  the  necessary  variable  definitions,  a  call  of  SAMPLER, 
and  screen  output  of  the  return  parameters.  Post-test,  system  memory  was  then 
examined  with  the  ROM  monitor  routine  to  see  that  data  had  been  loaded  into 
memory.  During  the  test  a  slowly  varying  square  wave  was  fed  into  the  analog 
input.  A  square  wave  was  used  so  that  only  two  digital  values  should  appear  in 
the  memory.  Well,  the  program  executed,  Sampler  Module  requested  a  go 
signal,  interrupts  began,  data  was  collected  in  memory.  However,  program 
execution  never  left  Sampler  Module  to  return  to  the  PLZ  routine.  A  whole 
bunch  of  time  was  spent  trying  to  find  out  why  this  occured.  No  answer  was 
found. 


Known  Problems  in  Sampler  Module 

As  discussed  in  the  testing  section  above,  Sampler  Module  never 
properly  interfaced  with  a  calling  PLZ  routine.  The  cause  of  this  problem  is  still 
unknown. 


Content  of  Detailed  Routine  Descriptions 

Following  are  detailed  descriptions  of  the  twelve  assembly  language 
routines  of  the  Sampler  Module.  With  a  few  exceptions,  the  following  items  will 
be  presented  for  each  of  the  routines. 

1 .  Routine  Name 

2.  Module  Name  and  Role  of  Routine 

3.  Language  and  Length  of  Routine 

4.  Synopsis  of  Routine 

5.  Routine  Relationship  Diagram 

6.  Invocation  of  Routine 

7.  Variables  and  Constants  Used  by  Routine 

8.  Discussion  of  Other  Routines  Called 
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9. 

10. 

11. 


Output  of  Routine 
Routine  Testing 
Reference  to  Routine  Listing 


The  routine  testing  discuss’ons  are  limited  to  activities  beyond  those  addressed 
in  the  module  testing  discussion  above.  The  listing  of  routines  of  Sampler  Mod¬ 
ule  are  in  Appendix  D. 
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1.  Routine  Name:  SAMPLER 

2.  Executive  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  16  lines  (42  bytes)  of  code. 


4.  Svnoosis  of  Routine 

SAMPLER  is  the  executive  routine  of  Sampler  Module.  This  assembly 
language  routine  is  the  entry  routine  of  the  module  and  is  in  effect  the  routine 
called  by  the  PLZ  program.  It  manages  overall  program  flow  within  the  module 
by  calling  nine  subordinate  routines  an  by  using  conditional  branching  based  on 
error  checking  and  user  readiness  checks.  SAMPLER  also  handles  a  portion  of 
the  PLZ  subroutine  call  overhead  and  performs  the  jump  back  to  the  calling  PLZ 
routine.  Figure  42,  in  the  introduction  to  Sampler  Module,  shows  the  flow  of 
SAMLER,  the  conditional  branches,  and  the  routines  called  by  SAMPLER. 

The  following  discussions  are  specifically  restricted  to  the  16  lines  of 
code  which  are  called  SAMPLER.  This  is  a  rather  arbitriary  distinction.  While 
SAMPLER  does  little  more  than  call  nine  other  routines,  without  SAMPLER  those 
routines  would  not  function.  It  is  perhaps  best  to  view  SAMPLER  as  an  organizer 
of  the  Sampler  Module  rather  than  a  complete  software  routine.  The  discussion 
that  follows  centers  on  this  organizer  function. 


5.- Invocation 

Since  the  first  line  of  SAMPLER  is  the  entry  point  for  the  Sampler 
Module,  SAMPLER  is  the  routine  called  by  the  parent  PLZ  program.  Thus,  the 
invocation  of  SAMPLER  is  the  same  as  the  innvocation  for  the  Sampler  Module 
discussed  previously.  However,  SAMPLER  itself  uses  none  of  the  input  and 
output  parameters  of  that  invocation;  these  parameters  are  used  by  the  subor¬ 
dinate  routines  in  the  Sampler  Module.  The  subordinate  routines  do  depend 
upon  SAMPLER  to  load  the  IX  register  with  the  stack  pointer  value  so  they  can 
reach  the  parameters  with  offsets. 


6.  Variables  and  Constants 

SAMPLER  uses  no  declaired  variables  or  constants.  It  does  place  the 
current  value  of  the  stack  pointer  into  the  IX  register  so  that  it's  subordinate  rou¬ 
tines  can  access  the  input  and  output  parameters  with  offsets  from  the  IX  value. 
SAMPLER  also  uses  the  Zero  Flag  of  the  Z-80  CPU  to  determine  whether  to 
branch  upon  the  completion  of  VALIDATE  and  USER_READY? 
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7.  Other  Routines  Called 

As  discussed  in  the  introduction  to  the  Sampler  Module,  SAMPLER  is 
the  executive  routine  for  the  module.  As  such,  all  other  routines  of  the  module 
are  called,  either  directly  or  indirectly,  by  SAMPLER.  The  names  and  functions  of 
these  routines  was  also  presented  in  the  module  introduction.  Figure  42  in  the 
introduction  to  Sampler  Module  shows  when  in  the  flow  of  SAMPLER  each  sub¬ 
ordinate  routine  is  called. 

There  are  no  true  parameters  passed  between  SAMPLER  and  its  sub¬ 
ordinate  routines.  The  only  communication  SAMPLER  uses  is  the  status  of  the 
zero  flag  upon  completion  of  VALIDATE  and  USER_READY?.  For  both  of  these 
routines,  a  nonzero  flag  tells  SAMPLER  to  abort.  From  VALIDATE,  SAMPLER 
just  jumps  to  DEALLOCATE  to  satisfy  PLZ  subroutine  termination  requirements; 
from  USER_READY?  SAMPLER  must  call  both  CTC_OFF  (to  clear  the  counter 
timer  chip)  and  DEALLOCATE.  SAMPLER  expects  DEALLOCATE  to  load  the  HL 
register  with  return  address  of  the  calling  routine. 


8.  Output  of  Routine 

As  stated  above,  SAMPLER,  the  entry  routine  of  the  Sampler  Module, 
does  not  pass  parameters.  The  output  parameters  for  the  module  are  loaded  by 
VALIDATE,  USER.READY?,  or  COLLECTER.  Similarly,  SAMPLER  by  itself  does 
not  cause  any  system  configuration  changes,  though  the  unaborted  execution  of 
the  Sampler  Module  will  result  in  a  number  of  analog  to  digital  conversion  and 
storage  of  those  conversions  in  system  memory. 


9,.fiQutipe  Testing 

SAMPLER  was  not  independently  tested. 


10.  Reference  to  Listing 

The  program  listing  of  SAMPER  is  on  page  318  in  Appendix  D. 
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1.  Routine  Name:  VALIDATE 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  14  lines,  30  bytes,  of  code. 


4.  Synopsis  of  Routine 

VALIDATE  is  a  defensive  error  checking  routine  for  Sampler  Module. 
Upon  being  called  by  SAMPLER,  VALIDATE  compares  the  input  parameters 
against  their  defined  ranges  and  values.  If  an  out  of  tollerance  parameter  is 
detected,  VALIDATE  loads  a  descriptive  error  code  into  the  output  parameter 
ERROR_CODE's  location  and  returns  to  SAMPLER.  The  Z-80  CPU  zero  flag,  if 
reset  by  the  comparisons,  informs  SAMPLER  that  the  input  parameters  were  not 
valid. 


VALIDATE  looks  at  two  input  parameters,  IO_CHANNEL  and  CTC_ 
MODE.  IO_CHANNEL  has  a  defined  range  of  zero  to  fifteen.  If  IO_CHANNEL 
has  a  value  greater  than  fifteen,  ERROR_CODE  is  set  to  the  constant  CHANNEL_ 
INVALID.  CTC_MODE  has  two  possible  values  represented  by  the  constants 
FAST_MODE  and  SLOW_MODE.  If  CTC_MODE  has  any  other  value,  ERROR_ 
CODE  is  set  to  the  constant  MODE  INVALID. 


5-  Routine  .Relationship  Diagram 


SAMPLER 


System  Stack 


Figure  46.  Relationship  of  VALIDATE  to  SAMPLER  and  the  System  Stack. 
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VALIDATE,  as  an  assembly  language  subroutine,  is  invoked  by  SAM¬ 
PLER  solely  by  its  name  through  the  Z-80  CALL  instruction.  Though  VALIDATE 
has  no  formal  parameter  list  upon  invocation,  it  uses  two  of  the  input  parameters 
to  the  Sampler  Module,  IO_CHANNEL  and  CTC_MODE,  and  one  output  para¬ 
meter,  ERROR_CODE.  VALIDATE  accesses  these  parameters  through  offsets 
from  the  IX  register.  This  is  in  accordance  with  PLZ  paramter  passing  procedures 
discussed  in  the  introduction  to  the  Sampler  Module  and  in  the  Utility  Module 
discussion. 


VALIDATE  also  uses  the  Z-80  zero  flag  to  inform  SAMPLER  whether 
the  input  parameter  were  correct.  In  the  four  comparisons  are  performed  by 
VALIDATE,  a  nonzero  result  means  the  input  parameter  is  out  of  range.  The 
CPU's  zero  flag  is  set  by  the  nonzero  result  and  is  not  altered  by  the  load  and 
jump  relative  commands  which  follow  the  compairson.  Thus,  upon  return  to 
SAMPLER  a  true  zero  flag  means  the  input  parameters  were  correct  and  a  false 
zero  flag  indicates  flawed  input. 


7.  Variables  and  Constants 
a.  Global 


Beyond  the  input  and  output  parameters  IO_CHANNEL,  CTC_MODE, 
and  ERROR_CODE,  VALIDATE  uses  no  globally  defined  variables.  The  globally 
defined  constants  used  by  VALIDATE  are: 


■  Mill  11 

Value 

CHANNELJNVALID 

CA  hex 

Error  Code  for  bad  channel  number  code 

FAST_MODE 

87  hex 

CTC  command  for  prescale  of  16 

SLOW_MODE 

A 7  hex 

CTC  command  for  prescale  of  256 

MODEJNVALID 

CC  hex 

Error  Code  for  wrong  CTC  command 

b.  Module 

VALIDATE 

uses  no 

module  variables  beyond  employing  the  CPU 

zero  flag  to  indicate  acceptable  input  parameters.  The  module  level  constants 
used  by  VALIDATE  are 
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IO_CHANNEL 

0E  hex 

IX  register  offset  for  the  input  parameter 
IO_CHANNEL 

UPPER_FOUR 

11110000 

A  mask  to  find  higher  order  one's. 

ERROR_CODE 

10  hex 

IX  offset  for  output  parameter 
ERROR_CODE 

CTC_MODE 

0C  hex 

IX  offset  for  input  parameter  CTC_MODE 

8.  Other  Routines  Called 

VALIDATE  calls  no  other  routines. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

VALIDATE  loads  the  output  parameter  ERROR_CODE  with  the  appro¬ 
priate  code  when  it  detects  an  invalid  input  parameter.  The  Z-80  zero  flag 
passes  back  to  SAMPLER  whether  the  input  parameters  were  valid  or  not. 


b.  System  Configuration  Changes 

VALIDATE  produces  no  system  configuration  changes. 


10.  Routine  Testing 

a.  Description  of  Test 

VALIDATE  was  tested  in  conjunction  with  the  rest  of  the  Sampler 
Module.  Specifically  for  VALIDATE,  invalid  channel  numbers  (greater  than  15) 
and  CTC  commands  were  passed  into  Sampler. 


b.  Results  of  Test 

VALIDATE  caught  the  invalid  input  parameters;  VALIDATE  did  not 
reject  valid  input  parameters. 
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The  listing  of  VALIDATE  is  on  page  339  in  Appendix  D. 
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1.  Routine  Name:  ATODINIT 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  13  lines  (21  bytes)  of  code. 


4.  Synopsis  of  Routine 

ATODINIT  initializes  the  analog  to  digital  converter  of  the  AIO  board. 
This  assembly  language  routine  is  based  on  the  PLZ  language  routine  AIOJNIT. 
Upon  being  called  by  SAMPLER,  ATODINIT  performs  five  operations  as  shown  in 
the  figure  below.  First  the  AF  registers  are  saved  and  the  Z-80  interrupts  are  dis¬ 
abled.  The  AF  register  save  is  an  artifact  of  the  routine's  use  in  booting  the  de¬ 
velopment  system.  The  interrupts  are  disable  to  prevent  inadvertant  interrupts 
from  the  AIO  board  during  its  programming.  Next,  ATODINIT  sets  the  two  AIO 
ports  to  input  mode  by  writing  the  command  INMODE  to  both  ports’  command 
registers.  Third,  the  AIO  is  placed  in  polled  mode  by  writing  the  command  INT- 
DISABLE  to  the  command  registers.  Fourth,  the  data  registers  (upper  and  lower) 
are  cleard  to  ready  the  board  for  input.  Last,  the  Z-80  interrupts  are  enabled,  the 
AF  register  values  restored,  and  control  is  returned  to  SAMPLER. 


5.  Routine  Relationship  Diagram 


Figure  47.  Relationship  of  ATODINIT  to  SAMPLER  and  AIO  Board. 
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ATODINIT  is  invoked  simply  by  name.  It  is  self  contained,  having  no 
input  or  output  parameters. 


and  Constant 


ATODINIT  uses  no  variables.  It  uses  six  global  constants  for  com¬ 
mands  and  10  port  addresses.  Their  names,  values,  and  definitions  are 

Constant  Name  Value  _ Definition _ 


InMode 

4F  hex 

AIO  Command  for  Polled  AtoD  Conversions 

CMD_A_PORT 

22  hex 

Address  of  AIO  Port  A  Command  Register 

CMD_B_PORT 

23  hex 

Address  of  AIO  Port  B  Command  Register 

INTDisable 

07  hex 

AIO  Command  for  Disabled  Interrupts 

DataLower 

20  hex 

Address  of  AIO  Lower  Data  Register 

DataUpper 

21  hex 

Address  of  AIO  Upper  Data  Register 

ATODINIT  calls  no  other  routines.  It  does  write  commands  to  the  AIO 


Board. 


ATODINIT  has  no  outputs.  Its  impact  upon  system  configuration  is  that 
the  AIO  board  in  now  in  polled  input  mode. 


ATODINIT  was  not  individually  tested.  ATODINIT  is  based  on  AIO_ 
IN  IT  and  is  used  in  other  programs  where  it  functions  properly. 
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0  11-  Reference  to  Listing 

The  listing  of  ATODINITs  assembly  language  code  is  on  page  340  in 
Appendix  D. 
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1.  Routine  Name:  CTC_PROGRAM 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  5  lines  (10  bytes)  of  code. 


4.  Synopsis  of  Routine 

CTC_PROGRAM  performs  the  initial  two  thirds  of  Counter  Timer  Chip 
One  (CTC1)  programming  by  writing  the  timer  mode  command  and  the  CTC 
portion  of  the  interrupt  vector  to  the  Channel  0  Command  Register.  CTC_PRO- 
GRAM  obtains  the  mode  command  from  the  system  stack  as  it  is  the  Sampler 
Module  input  parameter  CTC_MODE.  The  remaining  one  third  of  the  CTC 
programming  is  accomplished  by  START_TIMER. 


5.  Routine  Relationship  Diagram 


Figure  48.  Relationship  of  CTC_PROGRAM  to  SAMPLER,  the  CTC1 ,  and 

the  System  Stack. 


As  an  assembly  language  subroutine,  CTC_PROGRAM  is  invoked  by 
name  only  with  the  instruction  CALL  CTC_PROGRAM.  There  are  no  parameters 
formally  passed. 


CTC_PROGRAM  uses  one  variable,  the  input  parameter  CTC_MODE, 
which  it  obtains  from  the  system  stack  using  module  constant  CTC_MODE. 
CTC_MODE  (the  variable)  has  two  possible  values  87  hex  and  A7  hex  for  fast 
timer  with  interrupts  and  slow  timer  with  interrupts  respectively.  The  fast  timer 
uses  a  prescale  factor  of  1 6;  the  slow  timer  uses  a  prescale  factor  of  256.  The 
calling  PLZ  routine  selects  which  command  is  to  be  used  and  loads  CTC_MODE 
appropriately. 

CTC_PROGRAM  uses  three  module  constants.  Their  names,  values, 
and  deficitions  are 


IX  reg.  offset  for  input  parameter  CTC_MODE 
Address  of  CTC#1 ,  channel  0,  command  reg. 
The  CTC’s  portion  of  the  Interrupt  Vector 


Note:  the  other  half  of  the  interrupt  vector  is  in  the  Z-80  CPU  and  is  a  system  level 
constant  of  14  hex.  The  combination  of  the  two  halves  yields  the  address  1440 
hex,  the  location  in  the  interrrupt  jump  table  where  the  address  of  the  interrupt 
service  routine  will  be  placed  by  INT_SET_UP. 


CTC  PROGRAM  calls  no  other  routines. 


CTC_PROGRAM  has  no  output  parameters.  Upon  completion  of 
CTC_PROGRAM,  the  CTC  is  dormant,  two  thirds  of  the  way  programed  to  issue 
periodic  interrupts. 
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1.  Routine  Name:  INT_SET_UP 

2.  Subordinate  Routine  of  Sampler  Module 


3.  Written  in  Z-80  assembly  language;  9  lines  (19  bytes)  of  code. 


4.  Synopsis  of  Routine 

INT_SET_UP  establishes  the  interrupt  service  routine  for  Sampler 
Module.  There  are  two  parts  to  this  action.  First,  the  analog  input  channel  num¬ 
ber  is  loaded  into  the  alternate  A  register  (A')  of  the  Z-80  CPU.  INT_SET_UP 
gets  the  channel  number  from  the  input  parameter  IO_CHANNEL.  The  alternate 
register  set  is  used  by  the  interrupt  service  routine.  Second,  INT_SET_UP  sel¬ 
ects  which  interrupt  service  routine  will  be  used  based  on  the  input  parameter 
COUNT  and  loads  the  address  of  the  selected  routine  into  the  interrupt  jump 
table.  If  COUNT  has  a  value  of  zero,  routine  TO_SAMPLE  will  be  the  interrupt 
service  routine.  If  COUNT  is  nonzero,  TC_SAMPLE  will  be  used  and  INT_SET_ 
UP  loads  the  counter  values  into  the  BC'  and  DE'  registers.  The  starting  address 
of  the  selected  routine  is  placed  in  memory  location  1440  hex,  the  interrupt  jump 
table  location  for  CTC1 ,  channel  0  responses. 
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SAMPLER 


System  Stack 


Figure  49.  Relationship  of  INT_SET_UP  to  SAMPLER,  the  System  Stack, 
the  Interrupt  Jump  Table,  and  the  Z-80  CPU  Alternate  Registers. 


INT_SET_UP  is  invoked  with  "CALL  INT_SET_UP".  Being  an  assem¬ 
bly  language  routine,  there  are  no  formal  parameter  passing  lists.  INT_SET_UP 
does  expect  SAMPLER  to  have  properly  set  the  IX  register  so  that  input  para¬ 
meters  can  be  obtained  via  IX  register  offsets. 


INT_SET_UP  uses  the  input  parameters  IO_CHANNEL  and  COUNT.  It 
uses  six  global  constants  for  IX  register  offsets,  interrupt  service  routine  ad¬ 
dresses,  and  the  interrupt  jump  table  address.  These  constants,  their  values, 
and  their  definitions  follow. 


Sampler  Module 


10  CHANNEL 


0E  hex 


IX  offset  for  input  parameter  IO_CHANNEL 


COUNT 

08  hex 

IX  register  offset  for  input  parameter  COUNT 

ZERO 

00  hex 

Just  zero 

TO_SAMPLE 

undefined 

Beginning  Address  of  Interrupt  Service 
Routine  TO_SAMPLE,  defined  upon 
program  load 

TC_SAMPLE 

undefined 

Beginning  Address  of  Interrupt  Service 
Routine  TC_SAMPLE,  defined  upon 
program  load 

INT_JUMP_TABLE 

1440  hex 

Address  of  Interrupt  Jump  Table  location  for 

CTC1 ,  Channel  0  Interrupt  Services 


IN T  SET  UP  calls  no  other  routines. 


INT_SET_UP  has  no  output  parameters.  Its  impact  on  system  con¬ 
figuration  is  the  loading  of  the  selected  interrupt  service  routine's  starting  address 
into  the  interrupt  jump  table  and  the  loading  of  the  CPU’s  alternate  register  set 
with  the  values  needed  by  the  interrupt  service  routine. 


INT_SET_UP  was  not  specifically  individually  tested.  However,  dur¬ 
ing  the  overall  testing  of  Samper  Module,  it  was  verified  that  the  proper  ad¬ 
dresses  were  loaded  into  the  interrupt  jump  table  and  the  CPU  alternate  regis¬ 
ters  were  loaded  with  the  proper  values. 


The  program  listing  of  INT_SET_UP  is  on  pages  342-343  in  Appendix 
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1.  Routine  Name:  INIT_COLLECTOR 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language:  5  lines  (13  bytes)  of  code. 


INIT_COLLECTER  loads  into  the  Z-80  CPU’s  primary  register  set  the 
values  required  by  routine  COLLECTER  to  load  data  into  the  memory  buffer  and 
to  count  the  number  of  samples  collected.  The  address  for  the  first  storage  loca¬ 
tion,  FIRST_DATA,  is  loaded  into  the  DE  register  and  the  number  of  samples  to 
be  collected,  NUM_SAMPLES,  is  loaded  into  the  BC  register.  INIT_COLLECTER 
obtains  the  values  from  the  system  stack  as  they  are  input  parameters  to  Sampler 
Module  from  the  calling  PLZ  routine. 


SAMPLER 


System  Stack 
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6.  Invocation 

INIT_COLLECTER  is  called  by  SAMPLER  though  the  Z-80  instruction 

CALL. 

7.  Variables  and  Constants 

INIT_COLLECTER  uses  two  input  parameters,  FIRST_DATA  and  NUM_ 
SAMPLES,  which  it  obtains  from  the  system  stack  with  two  module  constants. 
These  constants,  their  values,  and  their  definitions  are 

Constant  Name_  Value  _ Bfifjpitign _ 

FIRST_DATA  04  hex  IX  offset  for  input  parameter  FIRST_DATA 

NUM_SAMPLES  06  hex  IX  offset  for  input  parameter  NUM_SAMPLES 

8.  Other  Routines  Called 

INIT_COLLECTER  calls  no  other  routines. 

9.  QutpuLof  Routine 

The  sole  effect  of  INIT_COLLECTER  is  the  loading  of  the  BC  and  DE 
registers  with  the  values  of  the  input  parameters  NUM_SAMPLES  and 
FIRST_DATA. 

10.  Routine  Testing 

INIT_COLLECTER  was  not  tested  apart  from  the  rest  of  the  Sampler 
Module  routines. 

11.  Reference  to  Listing 

INIT_COLLECTER's  program  listing  is  on  page  344  in  Appendix  D. 


Sampler  Module 


187 


1.  Routine  Name:  USER  READY? 


2.  Subordinate  Routine  of  Sampler  Module 


3.  Written  in  Z-80  assembly  language;  33  lines  (86  bytes)  of  code. 


USER_READY?  asks  the  user  of  the  system  whether  all  is  ready  for 
data  collection.  It  serves  as  the  "trigger"  to  begin  the  data  collection.  Figure  51 
below  shows  USER_READY?'s  relationship  to  SAMPLER  and  the  operating 
system.  For  this  thesis  effort,  the  user  typing  a  "Y"  on  the  system  keyboard  tells 
Sampler  Module  to  begin  data  collection.  If  other  types  of  triggers  were  desired, 
alternatives  to  USER_READY?  could  be  written  and  substituted  into  Sampler 
Module. 

The  sequence  of  operaions  in  USER_READY?  is  shown  in  Figure  52 
below.  USER_READY?  begins  by  loading  the  output  parameter  ERROR_CODE 
with  FALSE,  indicating  no  error.  Then  USER_READY?  calls  the  operating  sys¬ 
tem  to  output  the  message  "Collection  system  ready.  Begin  ?"  to  the  system  con¬ 
sole.  This  call  requires  extensive  preparation  and  loading  of  a  transfer  buffer. 
Next  USER_READY?  again  calls  the  system  to  obtain  the  user's  response  from 
the  system  keyboard.  This  call  also  requires  extensive  preparation  and  loading 
of  the  transfer  buffer.  Execution  will  remain  with  the  operating  system  until  the 
user  types  in  a  character.  Thus  execution  of  Sampler  Module  is  suspended  until 
the  user  responds.  When  the  user  responds,  USER_  READY?  checks  to  see 
whether  the  character  typed  in  is  a  "Y".  If  it  is,  USER_READY?  exits  to  SAM¬ 
PLER.  Otherwise,  ABORT  is  loaded  into  the  output  parameter  ERROR_CODE. 
The  failed  compairson  of  the  input  character  with  "Y"  puts  the  zero  flag  to  zero. 
The  zero  flag's  status  will  be  retained  during  the  return  to  SAMPLER  and  will 
indicate  to  SAMPLER  that  the  user  has  aborted  the  data  collection. 
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SAMPLER 


System  Stack 


Figure  51 .  Relationship  of  USER_READY?  to  SAMPLER,  the  System 
Stack,  the  Z- 80  Primary  Registers  and  the  RIO  Operating  System. 
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To  Other  Sampler  Module  Routines 


Figure  52.  Program  Flow  within  USER_READY? 
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USER_READY?  is  invoked  from  SAMPER  simply  by  its  name. 


7.  Variables  and  Constants 

a.  Variables 

USER_READY?  uses  three  variables.  USER_READY?  loads  the 
output  parameter  ERROR_CODE  with  either  FALSE  or  ABORT  to  indicate  to  the 
calling  PLZ  routine  whether  and  error  abort  occured  or  not.  The  second  variable 
used  is  the  character  returned  from  the  operating  system  call  to  the  system  key¬ 
board.  This  variable  is  located  in  the  buffer  location  RTN_MESS.  The  last  vari¬ 
able  used  is  not  a  true  variable,  rather  it  is  the  state  of  the  Z-80  zero  flag.  The 
state  of  this  flag  is  used  to  indicate  to  SAMPLER  whether  Sampler  Module  should 
continue  execution  or  be  terminated. 

b.  Constants 


USER_READY?  uses  a  host  of  module  constants.  Their  names, 
values,  and  definitions  follow.  Of  particular  interest  are  the  definitions  of  the 
Operating  System  Call  Vector  constants. 


Constant  Name 

Value 

Definition 

FALSE 

00  hex 

All  is  OK  Error  Code. 

ERROR_CODE 

10  hex 

IX  offset  for  output  parameter 
ERROR_CODE. 

A_VECTOR 

undefined 

Beginning  Address  of  the  Buffer  for  the 
Operating  System  Call  Vector,  de¬ 
fined  during  Module  linking. 

A_LOGICAL_UNIT 

A_VECTOR + 
00  hex 

Call  Vector  Position  for  Logical  Unit 
Desired. 

A_REQUEST_CODE 

A_VECTOR  + 
01  hex 

Call  Vector  Position  for  the  System 
Request  Code.  See  WRITELN  and 
READLN  below. 

A_DAT A_TRAN  S 

A.VECTOR  + 
02  hex 

Call  Vector  Position  for  Pointer  to  Data 
Transfer  location.  See  MESSAGE 
and  RTN  MESS. 

Sampler  Module 


191 


A_BYTE_COUNT 

A_VECTOR + 
04  hex 

Call  Vector  Position  for  Number  of  Bytes 
to  Be  Transfered. 

A_RETURN 

A_VECTOR  + 
06  hex 

Call  Vector  Position  for  the  No  Error 
Return  Address. 

A_ERR_RETURN 

A_VECTOR  + 
08  hex 

Call  Vector  Position  for  Error  Return 
Address 

A_COMP_CODE 

A_VECTOR  + 
0A  hex 

Call  Vector  Position  for  Operating 
System  Completion  Code. 

CONOUT 

02  hex 

Logical  Unit  Number  for  System 

Console. 

WRITELN 

10  hex 

Request  Code  for  Output. 

MESSAGE 

undefined 

Address  of  first  character  of  message 
"Collection  system  ready..  Begin  T 
Address  defined  upon  Module 

Unking. 

L_MESSAGE 

21  hex 

Length  of  MESSAGE. 

SET? 

undefined 

Address  of  a  Section  of  USER_ 
READY?,  used  for  A  RETURN  and 
A_ERR_RETURN.  Defined  at  Time 
of  Module  Linking. 

SYSTEM 

1 403  hex 

Address  of  Operating  System  Entry 
Point. 

CONIN 

01  hex 

Logical  Unit  Number  for  System 
Keyboard 

READLN 

0C  hex 

Request  Code  for  input. 

RTN_MESS 

undefined 

Address  of  a  buffer  used  to  receive  the 
User's  response.  Defined  during 
linking. 

Sampler  Module 


192 


undefined 


Y  ASCII 


59  hex 


Address  of  a  Section  of  USER_READY? 
used  as  the  A_RETURN  and 
A_ERR_RETURN.  Defined  at  Time 
of  Module  Linking. 

The  ASCII  character  "Y". 


ABORT 


AB  hex  Error  Code  for  User  Aborted  Data 
Collection. 


USERJREADY?  calls  the  operating  system  to  output  a  message  and 
to  receive  user  go  ahead  for  data  collection.  The  call  to  the  operating  system  is 
accomplished  by  loading  a  transfer  buffer  know  as  an  Operating  System  Call 
Vector  with  the  information  required  by  the  operating  system,  loading  the  ad¬ 
dress  of  the  buffer  into  the  IY  register,  and  then  calling  the  operating  system.  The 
call  vector's  content  is  shown  above  in  the  A_VECTOR  definitions  in  the  list  of 
constants  used  by  USER_READY?. 


The  output  of  USER_READY?  is  the  status  of  the  Z-80  CPU's  zero 
flag.  If  the  Z  flag  is  set  (a  one),  then  the  user  responded  with  a  "Y"  and  data 
collection  should  proceed.  If  the  Z  flag  is  not  set  (a  zero),  then  data  collection 
should  be  aborted. 


Module. 


USER_READY?  was  tested  along  with  the  other  routines  of  Sampler 


The  listing  of  USER_READY?  is  on  pages  345-346  in  Appendix  D. 
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1.  Routine  Name:  STARTTIMER 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  3  lines  (6  bytes)  of  code. 


4.  Svnoosis  of  Routine 

This  sole  purpose  of  this  very  short  routine  is  to  supply  the  final  third  of 
the  CTC  programing  begun  by  CTC_PROGRAM.  The  effect  of  this  is  to  turn  on 
the  CTC  timer  and  interrupts.  START_TIMER  obtains  the  command  it  writes  to 
CTC1 ,  channel  zero,  from  the  system  stack.  The  command  is  the  input  para¬ 
meter  TIME  CNST. 


5.  Routine  Relationships  Diagram 


Figure  53.  Relationship  of  START_TIMER  to  SAMPLER,  CTC1 ,  and  the 

System  Stack 


6.  Invocation 

START_TIMER  is  invoked  by  name  only  through  the  Z-80  instruction 
CALL.  There  are  no  parameter  passing  lists  in  assembly  language  subroutine 
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calls. 


START_TIMER  uses  one  variable,  the  input  parameter  TIME_CNST. 
This  variable  is  obtained  from  the  system  stack  via  the  module  constant  TIME_ 
CNST  (value  0A  hex)  which  is  the  IX  register  offset  to  the  input  parameter's  loca¬ 
tion  on  the  stack.  START_TIMER  also  uses  the  module  constant  CTC1_CMD 
(value  84  hex)  which  is  the  address  of  the  CTC1 ,  channel  0  command  register. 


START  TIMER  calls  no  other  routines. 


The  impact  of  START_TIMER  is  significant.  By  writing  the  time  con¬ 
stant  to  the  CTC,  the  CTC  programming  is  complete  and  it  begins  its  timing  and 
interrupting. 


No  individual  testing  was  performed  on  START_TIMER. 


The  program  listing  of  START_TIMER  can  be  found  on  page  347  in 
Appendix  D. 


Sampler  Module 


195 


1.  Routine  Name:  COLLECTER 


2.  Subrodinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  15  lines  (30  bytes)  of  coda. 

4.  Synopsis  of  .Routine 


COLLECTER  is  the  heart  of  Sampler  Module.  COLLECTER  reads  in 
the  data  from  the  AIO  board  and  stores  it  a  memory  buffer.  COLLECTER  con¬ 
tinues  to  read  in  data  until  the  specified  number  of  samples  have  been  collected. 


The  executation  states  of  COLLECTER  were  shown  in  Figure  43  in  the 
introduction  to  the  Sampler  Module.  COLLECTER  primarly  sits  in  a  loop,  check¬ 
ing  the  AIO  board  status  register  until  the  least  significant  bit  becomes  a  one 
signaling  that  data  is  ready.  The  lower  eight  bits  of  data  is  then  read  in  and 
stored  in  a  tempory  buffer  whose  address  is  stored  in  the  HL  register.  The  lower 
t  data  is  then  transfered  into  the  data  buffer.  The  rather  complex  Z-80  instruction 

LDI  handles  the  transfer  of  the  data  (HL  &  DE  registers),  the  decrementing  of  the 
sample  count  (BC  register)  and  incrementing  the  pointer  to  the  next  buffer  loca¬ 
tion  (DE  register).  The  upper  four  bits  are  then  read  in  (in  an  eight  bit  word), 
stored  in  a  tempory  buffer,  and  then  stored  in  the  data  buffer,  again  with  the  LDI 
instruction.  If  the  down  counter  (BC  register)  has  not  reached  zero,  COLLECTER 
returns  to  its  AIO  status  register  checking  loop.  If  all  the  samples  have  been 
collected,  COLLECTER  ends,  returning  program  execution  to  SAMPLER. 
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SAMPLER 


COLLECTER 


System 

Memory 


Data  Registers 


BC  Register 


HL  Register 


Figure  54.  Relationship  of  COLLECTER  to  SAMPLER,  System  Memory, 
the  Z-80  Primary  Registers,  and  the  AIO  Board. 


COLLECTER  is  invoked  by  name  only.  There  are  no  parameter  lists. 


a.  Variables 

While  COLLECTER  uses  no  named  variables,  the  primary  registers  of 
the  Z-80  CPU  and  some  memory  buffers  are  used  to  hold  the  values  necessary 
for  COLLECTER  to  execute.  The  interrupt  service  routine,  operating  concurrently 
with  COLLECTER,  uses  the  alternate  registers  of  the  CPU  to  hold  the  values  it 
needs.  The  registers  and  memory  buffers  used  by  COLLECTER  are 
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A  Receives  the  data  from  the  AIO  board  via  the  IN, A  instruction.  The 

data  is  then  placed  in  the  temporary  buffers. 

BC  Holds  the  down  counter  for  the  number  of  samples.  BC  is  loaded  by 
INIT_COUNTER.  BC  is  decremented  by  the  two  LDI  instructions 
used  in  COLLECTER.  An  INC  BC  is  included  in  COLLECTER  to 
keep  the  BC  value  the  number  of  samples,  not  the  number  of  data 
bytes  written  to  the  memory  buffer. 

DE  Holds  the  address  of  the  next  memory  buffer  location.  INIT_COL- 
LECTER  loads  DE  with  the  beginning  address  of  the  buffer.  DE  is 
incremented  by  LDI.  So  that  DE  holds  the  address  of  the  lower  half 
of  the  last  sample  stored,  DE  is  decremented  by  COLLECTER  upon 
its  termination. 

HL  Helds  the  address  of  the  tempory  buffers  in  which  data  bytes  are 
placed.  HL  is  loaded  with  the  address  of  lower  temporary  buffer 
(DataLower)  in  COLLECTER's  AIO  status  loop.  The  first  LDI  in¬ 
crements  HL  so  it  points  to  the  upper  temporary  buffer  (DataUpper). 

L_BUFFER  A  memory  location  used  as  a  temporary  buffer  for  the  lower  eight 
bits  of  data  read  in  from  the  AIO  board.  HL  holds  the  address  of 
DataLower. 

H_BUFFER  A  memory  location  one  above  DataLower  which  is  used  as  a 
temporary  buffer  for  the  upper  data  byte  read  in  from  the  AIO  board. 
After  the  first  LDI,  HL  holds  the  address  of  DataUpper. 


b.  Constants 

COLLECTER  uses  five  module  constants  to  refer  AIO  registers  and 
buffer  registers.  These  constants,  their  values,  and  their  definitions  are  listed 
below 


Sampler  Module 


198 


L_BUFFER 

undefined 

The  address  of  a  memory  location  used  for 
temporary  storage  of  the  lower  AIO  data. 
The  value  of  L_BUFFER  is  defined 
when  Sampler  Module  is  linked. 

H_BUFFER 

undefined 

The  address  of  a  memory  location  used  for 
temporary  stroage  of  the  upper  AIO 
data.  This  location  is  one  above 
L.BUFFER. 

ATODSTATUS 

29  hex 

The  address  of  the  AIO  board  status 
register. 

DATALOWER 

20  hex 

Address  of  the  AIO  board  lower  data 
register. 

DATAUPPER 

21  hex 

Address  of  the  AIO  board  upper  data 
register. 
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1.  Routine  Name:  CTC_OFF 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language;  5  lines  (7  bytes)  of  code. 


4.  Synopsis  of  Routine 


The  sole  purpose  of  this  little  routine  is  to  turn  the  CTC  timing  and 
interrupting  off.  Is  is  accomplished  by  writing  the  off  command  to  the  command 
register  of  CTC  number  one  (CTC1).  Prior  to  writing  to  the  CTC,  Z-80  interrupts 
are  disabled  to  prevent  inadvertant  interrupts.  Z-80  interrupts  are  enabled  by 
CTC_OFF  prior  to  its  return  to  the  calling  routine,  SAMPLER. 


a 


> 

.V 

Ai 


1 


CTC_OFF  uses  no  variables.  It  does  use  the  following  two  global 


constants. 


CMD_CTC_OFF  78  hex  Command  to  hault  and  disable  interrupts 


CTC1  CMD 


84  hex  Command  port  address  for  CTC1 ,  channel  0 


CTC  OFF  calls  no  other  routines. 


CTC_OFF  has  no  output.  Its  impact  on  system  configuration  is  to  turn 
off  the  CTC1 ,  channel  0  timer  and  inhibit  CTC1  from  issuing  interrupts. 


A  variant  of  CTC_OFF  was  successfully  used  in  another  program 
yielding  some  faith  that  CTC_OFF  would  function  properly.  For  this  effort  CTC_ 
OFF  was  tested  in  conjuction  with  the  rest  of  Sampler  Module  as  described  in  the 
module  discussion. 


The  program  listing  of  CTC_OFF  is  on  page  349  in  Appendix  D. 
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1 .  Routine  Names:  TO_SAMPLE  and  TC_SAMPLE 

2.  Interaipt  Service  Routines  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language; 

TO_SAMPLE:  4  lines  (6  bytes)  of  code; 
TC_SAMPLE:  19  lines  (25  bytes)  of  code. 


4,  Synopsis  of  Routine 

TO_SAMPLE  o  r  TC_SAMPLE  is  the  interrupt  service  routine  for  the 
Sampler  Module.  TO_SAMPLE,  for  "Timer  Only",  is  used  for  timer  periods  be¬ 
tween  50  microseconds  and  10  milliseconds.  TC_SAMPLE,  for  "Timer  and 
Counter,  is  used  for  timer  periods  between  10  milliseconds  and  29.3  minutes. 
Which  routine  is  used  is  determined  by  INT_SET_UP  based  on  the  input  para¬ 
meters  to  Sampler  Module.  INT_SET_UP  loads  the  starting  address  of  the  sel¬ 
ected  routine  into  the  interrupt  jump  table.  The  two  routines  service  the  CTC 
timer  interrups  differently. 

TO_SAMPLE  swaps  CPU  AF  register  banks,  outputs  to  the  AIO  chan¬ 
nel  select  port  the  desired  analog  input  channel,  swaps  the  AF  register  banks 
f  back,  and  then  returns  from  the  interrupt.  The  register  banks  are  swaped  to  gain 


Figure  56.  Relationship  of  TO_SAMPLE  to  CTC  Interrupts,  the  Z-80 
Alternate  Register  A,  and  the  AIO  Board. 
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access  to  the  A  register  of  the  alternate  register  set  which  holds  the  desired  ana¬ 
log  channel  number  and  to  prevent  interference  with  COLLECTER.  By  selecting 
an  AIO  input  channel,  an  analog  to  digital  conversion  is  initiated  on  that  channel. 

TC_SAMPLER  is  more  complicated.  To  achieve  the  longer  timing 
periods,  TC_SAMPLER  has  a  sixteen  bit  counter  decremented  by  each  interrupt. 
When  called,  TC_SAMPLE  first  swaps  the  AF,  BC,  DE,  and  HL  registers  to  protect 
the  contents  of  the  primary  bank  of  registers  and  to  gain  access  to  the  counter 
values  stored  in  the  alternate  bank  of  registers.  The  counter  is  then  decrement. 
When  the  counter  reaches  zero,  TC_SAMPLE  writes  the  desired  analog  input 
channel  number  to  the  AIO  board,  initiating  an  analog  to  digital  conversion,  and 
resets  the  counters.  Just  prior  to  returning  from  interrupt,  TC_SAMPLE  swaps  the 
primary  register  bank  back. 


Figure  57.  Relationship  of  TC_SAMPLE  to  CTC  Interrupts,  the  Alternate 
Registers  of  the  Z-80  CPU,  and  the  AIO  Board. 


5.  Invocation 

Neither  TO_SAMPLE  nor  TC_SAMPLE  are  "invoked."  Rather,  when  a 
CTC  initiated  interrupt  occurs,  one  of  these  routines  will  begin  execution. 
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Neither  TO_SAMPLE  nor  TC_SAMPLE  use  any  named  variables. 
Rather,  these  routines  make  use  of  values  saved  in  the  alternate  register  set  of 
the  Z-80  CPU.  Both  routines  use  the  alternate  A  register  (A')  to  hold  the  number 
of  the  user  specified  AIO  board  analogue  input  channel.  Both  routines  write  this 
number  to  the  AIO  channel  select  register  to  initiate  an  analog  to  digital  conver¬ 
sion.  TC_SAMPLE  also  uses  the  alternate  BC  (BC')  and  DE  (DE')  registers.  BC' 
holds  the  current  down  counter  value  that  is  decremented  with  each  call  of  TC_ 
SAMPLE.  DE'  holds  initial  value  of  the  down  counter;  DE'  is  used  to  reset  BC' 
when  the  counter  reaches  zero. 

Both  TO_SAMPLE  and  TC_SAMPLE  use  the  module  constant 
CHANNEL_SELECT  value  28  hex,  for  the  address  of  the  AIO  input  channel 
selection  register. 


7.  Other  Routines  Called 

TO_SAMPLE  and  TC_SAMPLE  call  no  other  routines. 


8.  Output  of  Routine 

In  the  single  execution  of  Sampler  Module,  TO_SAMPLE  or  TC_SAM- 
PLE  can  be  called  hundreds  to  thousands  of  times.  Each  time  TO_SAMPLE  is 
called,  an  analog  to  digital  conversion  is  initiated.  Each  time  TC_SAMPLE  is 
called  the  down  counter  is  decremented;  when  it  reaches  zero  an  analog  to  digi¬ 
tal  conversion  is  initiated. 


9.  Routine  Testing 

Both  TO_SAMPLE  and  TC_SAMPLE  were  tested  in  conjunction  with 
the  rest  of  the  Sampler  Module  routines.  Being  interrupt  service  routines  there  is 
no  way  they  could  be  tested  independently. 


10.  Reference  to  Listing 

The  listings  of  TO_SAMPLE  and  TC_SAMPLE  are  on  page  350  in 
Appendix  D. 
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1.  Routine  Name:  DEALLOCATE 

2.  Subordinate  Routine  of  Sampler  Module 

3.  Written  in  Z-80  assembly  language:  1 1  lines  (16  bytes)  of  code. 


4.  Synopsis  of  Routine 

DEALLOCATE  is  the  last  subordinate  routine  of  Samper  Module.  DE¬ 
ALLOCATE  handles  all  prepartions  for  the  return  to  the  calling  PLZ  routine.  Spe¬ 
cifically,  DEALLOCATE  loads  the  addresses  of  the  last  data  values  stored  into  the 
output  parameter  LAST_DATA's  storage  location  in  the  system  stack.  Then  DE¬ 
ALLOCATE  pops  the  calling  routine's  IX  regester  value  (into  IX)  and  the  return 
address  (into  HL)  from  the  system  stack.  Last,  DEALLOCATE  pops  from  the  sys¬ 
tem  stack  the  storage  locations  for  the  input  parameters.  Having  completed  its 
actions,  DEALLOCATE  returns  to  SAMPLER. 


5.  Routine  Relationship  Diagram 


SAMPLER 

DEALLOCATE 


Figure  58.  Relationship  of  DEALLOCATE  to  SAMPLER  and  the  System  Stack 


System  Stack 


6.  Invocation 

As  an  assembly  language  subroutine,  DEALLOCATE  is  invoked  by 
name  only.  There  is  no  parameter  passing. 
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DEALLOCATE  uses  no  variables.  It  does  use  the  module  defined 
constant  LAST_DATA,  value  12  hex,  for  the  IX  register  offset  to  the  storage  loca¬ 
tion  of  the  output  parameter  LASTED ATA.  DEALLOCATE  does  load  the  HL  re¬ 
gister  with  the  return  address  for  the  calling  routine. 


8.  Other  Routines  Called 

DEALLOCATE  calls  no  other  routines. 


9.  Output  of  Routine 

At  the  end  of  DEALLOCATED  execution,  the  HL  register  holds  the 
calling  routine’s  return  address,  the  IX  register  holds  the  calling  routine’s  original 
IX  value,  the  return  parameter  LAST_DATA  is  in  place  in  the  system  stack,  and 
the  input  parameter  storage  locations  in  the  system  stack  have  been  deallocated. 


IQ.  Routine  Testing 

DEALLLOCATE  was  tested  with  the  rest  of  Sampler  Module  routines. 


11. -Reference  to  Listing 

The  program  listing  of  DEALLOCATE  is  on  page  351  in  Appendix  D. 
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V.  Buffers  Module 


Definition  of  Buffers  Module 

Buffers  Module  is  unique  among  the  modules  of  the  data  collection 
system  in  that  it  contains  not  one  line  of  code.  Rather  than  code,  the  Buffers  Mod¬ 
ule  holds  the  definition  of  the  memory  buffer  that  Sampler  Module  loads  data  into 
and  that  routine  LOAD_DATA_FILE,  of  Collect_Data  Module,  reads  data  from 
and  writes  to  a  disk  file.  The  global  buffer  established  in  Buffers  Module  is 
named  DATA_BUFFER.  It's  declaira-  tion  statement  sizes  DATA_BUFFER  as  an 
array  of  BUFFER_SIZE  words  (sixteen  bits).  BUFFER_SIZE  is  a  Buffers  Module 
constant  having  a  value  of  1000  decimal.  Thus,  DATA_BUFFER  holds  2000 
bytes.  When  the  whole  data  collection  system  is  linked  together,  Buffers  Module 
is  the  last  module  linked  in. 

The  listing  for  Buffers  Module  is  in  Appendix  E. 
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VI.  Collect  Data  Module 


Introduction  to  Collect_Oata  Module 

Collect_Data  Module  is  a  set  of  PL 2  language  routines  which,  along 
with  some  external  routines,  implements  a  portion  of  a  data  collection  system. 
The  portion  implemented  is  the  reading  in  of  data  from  the  AIO  board  and  storage 
of  that  data  in  a  disk  file.  Collect.Data  Module  is  intended  to  be  called  from  a 
high  level  user  interface  routine. 

The  routines  of  Collect_Data  Module  presented  here  are  not  com¬ 
pletely  developed.  They  have  not  been  assembled  nor  linked  in  with  the  external 
routines  called.  These  routines  do  fully  represent  the  design  of  the  data  collec¬ 
tion  system. 

In  the  following  sections  the  organization  and  function  of  the  routines 
of  Collect_Data  Module  will  be  presented.  Following  that  will  be  a  listing  of  the 
external  routines  used,  a  description  of  the  invocation  of  Collect_Data,  the  varia¬ 
bles  and  constants  of  Co!ect_Data  Module,  and  the  known  flaws  in  the  module. 
Descriptions  of  the  fifteen  routines  of  Collect_Data  Module  are  then  presented. 


Organization  Qf  CoIlflCLData-Mfldulfl 

The  fifteen  routines  of  Collect_Data  Module  and  the  thirteen  external 
routines  used  by  Collect_Data  are  organized  into  a  hierarichal  structure.  There  is 
one  executive  routine,  SAMPLE_DATA,  which  calls  seven  subordinate  routines. 
Five  of  these  routines  are  primary  subordinate  routine  ;  they  control  the  five  major 
functions  of  Collect_Data.  The  routines  of  Collect_Data  and  their  functions  are 
listed  below.  The  numbered  routines  are  the  primary  subordinate  routines. 

_  Routing  Nams _  _ Function _ 

SAMPLE_DATA  Executive  routine  of  Collect_Data  Module. 

GET_DATE  Via  an  external  routine,  reads  the  system  date 

and  loads  the  six  characters  into  a  string. 

1 .  PREPARE_COLLECTOR  Finds  programming  commands  for  the  CTC,  the 

down  counter  value,  and  sizes  the  data  buffer. 
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FIND_TIME_CNST  Rounding  division  routine  to  find  the  CTC  time 

constant. 

FIND_CTC_COMMANDS  Based  on  user  inputs,  calculates  the  three 

values  needed  to  set  up  the  CTC  paced 
interrrupts. 

SIZE_DATA_BUFFER  Based  on  user  inputs,  establishes  the  data 

buffer. 

ERROR_IN_PREPARE  Manages  error  checking  and  error  messages  for 

PREPARE_COLLECTOR. 

2.  CREATE_DATA_FILE  Opens  a  disk  file  to  hold  the  data  read  in  by 

SAMPLER;  loads  header  information  into  the  file. 

ASCII  T ranslates  a  numeric  value  into  the  string  of 

ASCII  characters  that  represent  it. 

STRING_COPY  T ranscribes  a  string  of  characters  into  another 

string. 

VALID_STRING  Checks  the  contents  of  a  string  to  ensure  all 

characters  are  valid  for  a  file  name. 

ERROR_IN_CREATE  Error  determination  and  error  message  routine 

for  CREATE_DATA_FILE. 

3.  SAMPLER  Turns  on  the  CTC  interrupts,  programs  the  AIO 

analog  to  digital  converter,  and  reads  in  data 
from  the  AIO  Board  into  the  memory  buffer 
(external  routine  of  Sampler  Module) 

ERROR_IN_SAMPLER  Checks  the  output  of  SAMPLER  for  errors;  writes 

error  messages  to  the  system  console. 

4.  LOAD_DATA_FILE  Transfers  the  data  stored  by  SAMPLER  in  the 

memory  buffer  into  the  disk  file  opened  by 
CREATE_DATA_FILE. 

5.  CLOSE_DATA_FILE  Closes  the  disk  file  holding  the  data. 
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Figure  59.  Data  Flow  Diagram  for  Collect_Data  Module 


The  data  flow  diagram  above  shows  the  functional  relationships  be¬ 
tween  these  five  primary  proccesses  of  Collect_Data  Module.  It  is  not  coinsi- 
dence  that  the  names  of  the  five  primary  subordinate  routines  match  these  five 
processes.  The  inputs  to  Collect_Data  Module  are 
the  user  sampling  instructions, 
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the  user  "start"  command, 
analog  input  data  (via  the  AIO  board) 
and  the  system  data. 

The  outputs  of  Col!ect_Data  (assuming  all  goes  well)  are  messages  written  to  the 
system  console,  error  codes  to  both  the  system  console  and  the  calling  routine, 
and  a  disk  file  filled  with  data.  The  sole  controlling  factors  are  the  inputs  from  the 
user.  The  mechanisms  employed  to  accomplish  each  procedures’  purpose  is 
either  the  RIO  operating  system  or  the  AIO  board. 


External  Routines  Called  Bv  Collect  Data  Module  Routines 

Thirteen  external  routines  are  used  by  Collect_Data.  Their  names, 
invocations,  functions  and  modules  are  listed  below. 

- Enhancements  Module  Routines - 

a.  WRITE_HBYTE{  LOGICALJJNIT,  VALUE) 

where  LOGICALJJNIT  (type  Byte)  is  the  number  of  the  device  to  which  the  hexi- 
decimal  representation  of  VALUE  (type  Byte)  is  to  be  output. 


b.  WRITE_HINTEGER(  LOGICALJJNIT,  VALUE  ) 

where  LOGICALJJNIT  is  type  Byte  and  VALUE  is  type  Integer.  This  routine  is 
used  to  output  the  ASCII  characters  that  form  the  hexidecimal  representation  of 
VALUE. 


c.  WRITE_DWORD(  LOGICALJJNIT,  VALUE  ) 

where  LOGICALJJNIT  (type  Byte)  is  the  output  device  and  VALUE  is  the  number 
whose  decimal  representation  in  ASCII  characters  is  to  be  output. 


d.  WRITE_RCODE(  LOGICALJJNIT,  RETURN JX5DE  ) 

where  both  parameters  are  of  type  Byte.  LOGICALJJNIT  is  the  number  of  the 
output  device  driver.  RETURN_CODE  is  the  RIO  Operating  System  return  code 
whose  text  descritption  will  be  written  to  the  desired  device. 
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e.  WRITELN_RCODE(  LOGICAL_UNIT,  RETURN_CODE  ) 

performs  the  same  function  as  WRITE_RCODE  with  the  same  parameters  but 
adds  a  carriage  return  on  the  end  of  the  text  description. 


f.  WRITE(  LOG1CALJJNIT,  TEXT_POINTER) 

where  LOGICALJJNIT,  of  type  Byte,  designates  the  device  to  which  output  is 
directed.  TEXT_POINTER,  type  PByte  for  Pointer-To-Byte,  points  to  the  first 
character  of  the  text  string  to  be  output.  Characters  will  be  output  until  a  carriage 
return  is  encountered.  The  carriage  return  will  not  be  output. 


g.  WRITELN{  LOGICALJJNIT,  TEXT.POINTER  ) 
is  identical  to  WRITE  except  WRITELN  does  output  the  carriage  return. 


- PLZ.STREAM.IO  Module  Routines - 

h.  RETURN_CODE  :* 

OPEN(  LOGICALJJNIT,  FILE_NAME_PTR,  MODE  ) 

where  RETURN_CODE,  LOGICAL_UNIT,  and  MODE  are  type  Byte  and  FILE_ 
NAME_  PTR  is  type  PByte.  The  purpose  of  OPEN  is  to  open  a  disk  file.  RE* 
TURN_CODE  passes  back  the  RIO  operating  system  completion  code.  LOGI¬ 
CALJJNIT  passes  in  the  desired  logica  unit  number  for  the  file.  FILE_NAME_ 
PTR  points  to  the  first  character  of  a  text  string  which  holds  the  desired  file  name. 
MODE  pases  in  the  type  of  opening  desired. 


i.  RETURN J^ODE  :=  CLOSE(  LOGICALJJNIT ) 

where  both  parameters  are  type  Byte.  CLOSE'S  function  is  to  close  an  open  disk 
file.  RETURN  _CODE  passes  back  the  operating  system's  code  descriptor  of 
operation  performance.  LOGICALJJNIT  is  the  logical  unit  number  of  the  file  to 
be  closed. 


j.  RETURN JX)DE  :=  PUTSEQ(  LOGICALJJNIT,  BUFFER J^TR, 

N  U  MB  E  R_OF_B  YTE  S  ) 

where  RETURN  JSODE  and  LOGICALJJNIT  are  type  Byte,  BUFFER_PTR  is  type 
PByte,  and  NUMBER_OF_BYTES  is  type  Word.  PUTSEQ  outputs  the  string  of 
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characters  (or  byte  values)  pointed  to  by  BUFFER_PTR.  If  no  errors  occur,  NUM- 
BER_OF_BYTES  bytes  will  be  output  to  the  designated  LOGICAL_UNIT.  The  re¬ 
turn  parameter  RETURN_CODE  passes  back  the  operating  system  completion 
code. 


- Sampler  Module  Routine - 

k.  ERROR_CODE,  LAST_DATA  := 

SAMPLE R(  IO_CHANNEL,  CTC_MODE, 
TIME_CNST,  COUNT, 
NUM_SAMPLES,  FIRST_DATA  ) 

where  ERROR_CODE,  IO_CHANNEL,  CTC.MODE,  and  TIME_CNST  are  type 
Byte,  COUNT  and  NUM_SAMPLES  are  type  Word,  and  LASTJDATA  and 
FIRST_DATA  are  type  PByte.  SAMPLER  is  a  collection  of  assembly  language 
routines  which  activates  an  interrupt  driven  data  collection  effort  that  yields  a 
memory  buffer  full  of  data.  IO_CHANNEL  is  the  AIO  board  input  channel  desired. 
CTC_MODE  and  TIME_CNST  are  the  programming  values  for  the  CTC  chip. 
COUNT  is  the  value  required  for  a  down  counter.  CTC_MODE,  TIME_CNST,  and 
COUNT  jointly  define  the  sampling  interval.  NUM_SAMPLES  is  the  number  of 
12-bit  analog  to  digital  conversion  values  to  be  read  in.  FIRSTJDATA  points  to 
the  beginning  of  the  data  buffer.  Upon  return,  LAST_DATA  points  to  the  last  data 
location  in  memory.  ERROR_CODE  returns  a  sing  byte  code  for  routine  perfor¬ 
mance  indications. 


Invocation  of  Collect  Data  Module 

As  indicated  in  the  introduction,  Collect_Data  Module  is  intended  to 
be  called  from  a  higher  level  user  interface  routine.  The  executive  routine 
SAMPLE_DATA  is  the  interface  between  the  calling  routine  and  Collect_Data 
Module.  Its  invocation  is 

ERROR_CODE  :=  SAMPLE_DATA  (  TESTID,  USER_MESSAGE, 

PERIOD_VALUE,  PERIOD_UNITS, 
INPUT_CHANNEL,  SAMPLES  ) 

the  type  and  purpose  of  these  parameters  is  listed  below. 
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Parameter. 


Purpose 


Tyga 

TESTID  ASCII_STRING  A  six  character  string  (plus  a  carriage 

return)  that  is  a  unique  identifier  for  the 
data  file,  a  test  identifier. 


USER  MESSAGE 


ASCII  STRING 


A  free  field  string  of  characters  (up  to  32)  of 
user  message  for  inclusion  in  the  data  file. 


PERIOD_VALUE 

Integer 

The  number  of  time  units  (units  given  by 
PERIOD_UNITS)  in  the  sampling  period. 

PERIOD_VALUE 

Integer 

The  units  of  PERIOD_VALUE.  Three  are 
defined;  microseconds,  milliseconds,  and 
seconds. 

INPUT_CHANNEL 

Byte 

The  AIO  board  input  channel  (0-15)  to  be 
used. 

SAMPLES 

Word 

The  number  of  data  samples  to  be 
collected. 

ERROR_CODE 

Byte 

A  one  byte  code  passed  back  to  indicate 

the  degree  of  success  of  Collect_Data 
Module. 


For  SAMPLE_DATA  to  be  called  and  function,  Collect_Data,  Enhancements, 
Sampler,  and  PL2.STREAM.IO  modules  must  all  be  linked  in  with  the  calling 
routine. 


Collect  Data  Module  Variables  and  Constants 

There  are  no  module  level  variables  used  by  any  of  the  Collect_Data 
routines.  Other  than  the  input  /  output  parameters  and  the  global  buffer  DATA_ 
BUFFER,  no  global  variables  are  used  by  any  module  routines.  Quite  a  few  con¬ 
stants  are  used  however.  Their  names,  values,  and  definitions  are  listed  on  the 
following  page. 
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MICRO_SECONDS 

-6  dec 

A  possible  value  for  the  input  parameter 
PERIODJJNITS. 

MILLI_SECONDS 

*3  dec 

A  value  for  the  input  parameter 
PERIODJJNITS. 

SECONDS 

0  dec 

Third  possible  value  for  PERIODJJNITS 

SLOW_MODE 

87  hex 

A  programming  word  for  the  CTC  indi¬ 
cating  an  interrupting  timer  with  a  pre¬ 
scale  factor  of  256.  It  is  one  of  the  pos¬ 
sible  values  passed  to  SAMPLER  via 
its  input  parameter  CTC__MODE. 

FAST_MODE 

A 7  hex 

A  programming  word  for  the  CTC  indi¬ 
cating  an  interrupting  timer  with  a  pre¬ 
scale  factor  of  1 6.  It  is  one  of  the  pos¬ 
sible  values  passed  to  SAMPLER  via  its 
input  parameter  CTC_MODE. 

END_OF_STRING 

7C  hex 

The  ASCII  character "  | "  which  is  used  to 
indicate  end  of  string. 

END_OF_FILE 

FF  hex 

MCB  standard  end  of  file  designator. 

MINIMUM_TIME 

50  dec 

The  minimum  number  of  microseconds 
permitted  for  the  sampling  period. 

CONSOLE_OUT 

2  hex 

The  logical  unit  number  for  the  system 
screen. 

DATA_FILE 

7  hex 

The  logical  unit  number  chosen  for  the 
disk  file. 

BUFFER_SIZE 

1000  hex 

An  arbitrary  selected  maximum  for  the 

data  buffer. 

MAX_BUFFER_ADDRESS 

9A00  hex  The  upper  memory  address  allowable 
for  the  data  buffer.  The  value  is  based 
on  where  the  operating  system  and  the 
data  collection  routines  are  loaded. 
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Constant  Name  Value  _ Definition 

—  Error  Codes  of  Collect  Data  Module - 


FALSE  00  hex 


FATAL 

FE  hex 

ABORT 

AB  hex 

TOO_MANY_SAMPLES 

E0  hex 

BAD_CHARACTER 

BC  hex 

PERIOD_RANGE_ERROR 

El  hex 

REDO 

22  hex 

STORAGE_ERROR 

23  hex 

_ Constant  Name _ 

_ Value _ 

- RIO  Operating  System  Return 

OPERATION_COMPLETE 

80  hex 

DUPLICATE  FILE 

D0  hex 

INSUFFICIENT_MEMORY 

4A  hex 


No  error. 

Things  have  gone  very  wrong.  Fatal 
error. 

The  user  has  signaled  to  hault  data 
collection. 

The  user  specified  more  samples  than 
there  is  buffer  space  for. 

A  character  in  a  file  name  string  is 
invalid. 


The  user  specified  the  sampling  interval 
improperly  or  selected  an  invalid  range. 

The  user  input  was  not  correct. 

Something  went  wrong  during  the 
transfer  of  data  from  the  memory  buffer 
to  the  disk  file. 


Definition 
Codes  Used  by  Collect_Data 


The  requested  action  was  successfully 
executed. 

The  file  name  passed  during  an  open 
new  file  operation  already  exists. 


A  memory  manager  return  if  a  memory 
allocation  request  cannot  be  satisfied. 


a 


3 
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DEVICE  NOT  READY  C2  hex 


Code  for  a  device,  such  as  a  disk  drive, 
being  unable  to  respond. 


FILE_NOT_FOUND  C7  hex  Return  for  an  OPEN  request,  other  than 

create,  when  the  desired  file  isn’t  on  the 
disk  directory. 

Note:  no  constants  are  defined  at  the  routine  level. 


Flaws . in  Collect  Data  Module 

Aside  from  the  fact  that  this  module  was  never  assembled,  there  are  a 
number  of  flaws  present  in  Collect_Data  Module.  Most  of  these  flaws  are  pre¬ 
sented  in  the  discussions  of  the  individual  routines.  Two  errors  are  present  in  the 
module  overhead  however.  First,  in  the  introductionary  comments,  the  third  rou¬ 
tine  listed  should  be  SAMPLER  not  SAMPLE_DATA.  SAMPLE.DATA  is  the  exe¬ 
cutive  routine  for  Collect.  Data  Module.  The  second  error  is  more  serious.  In  the 
externals  definition  section,  the  order  of  parameters  for  SAMPLER  is  in  error.  The 
SAMPLER  definition  should  appear  as 

SAMPLER  PROCEDURE(  KDCHANNEL  CTC.MODE  TIME.CNST  BYTE, 

COUNT  NUM.SAMPLES  WORD, 

FIRST.DATA  PBYTE  ) 

RETURNS  (  ERROR.CODE  BYTE,  LAST.DAT A  PBYTE  ) 

In  attition  to  these  two  specific  flaws,  the  comments  of  the  Collect.Data  Module 
routines  just  is  not  sufficient.  This  is  particularly  true  of  the  later  routines.  Last, 
some  of  the  constants  defined  for  Collect.Data  Module  and  one  external  routine 
(SEEK)  are  not  used  by  the  module. 


Content  of  Detailed  Routine  Descriptions 

In  the  following  pages  are  detailed  descriptions  of  the  fifteen  routines 
of  the  Collect.Data  Module.  In  each  description,  the  following  information  will  be 
presented. 

1 .  Routine  Name 

2.  Name  of  Module  and  Role  of  Routine 

3.  Language  and  Length  of  Routine 
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4.  Synopsis  of  Routine 

5.  Diagram  of  Routine  Relationships 

6.  Invocation  of  Routine 

7.  Variables  and  Constants  Used 

8.  Other  Routines  Called 

9.  Output  of  Routine 

1 0.  Flaws  in  the  Routine 

1 1 .  Reference  to  the  Routine  Program  Listing 

The  program  listings  of  Collect_Data  Module  are  in  Appendix  F. 
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1 .  Routine  Name:  STRING_COPY 

2.  Internal  routine  of  Co!lect_Data  Module. 

3.  Written  in  PL Z,  seven  lines  of  code. 


4.  Synopsis  of  Routine 

Procedure  STRING_COPY  transcribes  a  string  of  ASCII  characters 
from  one  memory  location  to  another.  Since  PL Z  cannot  directly  refer  to  absolute 
memory  addres-ses,  pointers  to  the  source  and  destination  strings  are  used.  The 
beginning  of  the  source  string  is  pointed  to  by  the  input  parameter  SOURCE;  the 
beginning  of  the  destination  string  location  is  pointed  to  by  the  input  para  meter 
DESTINATION.  The  transcription  begins  by  copying  the  character  at  location 
SJNDEX  of  SOURCE  to  location  DJNDEX  of  DESTINATION  where  SJNDEX 
and  DJNDEX  are  offsets  from  the  beginnning  of  the  strings.  Both  SJNDEX  and 
DJNDEX  are  input  parameters  to  Procedure  String_Copy.  Transcription 
continues  character  by  character  until  the  ASCII  character  "|"  (7C  hex)  is  copied 
from  SOURCE  to  DESTINATION.  The  "|"  is  thus  used  as  an  end  of  string  de¬ 
limeter  and  is  the  module  constant  END_OF_STRING. 


5,  Routine  Relationship  Diagram 


CREATE J 

)ATA_FILE 

STRING_COPY 

_ 

Figure  60.  Relationship  Between  STRING_COPY  and 
CREATE  DAT  FILE 


6.  invocation 

STRING_COPY  is  invoked  from  CREATE_DATA_FILE  with 
STRING_COPY(  SOURCE,  SJNDEX,  DESTINATION,  DJNDEX  ) 
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where  SOURCE  and  DESTINATION  are  of  type  ASCII_PTR  (  a  pointer  to  an 
ASCII  string)  and  SJNDEX  and  DJNDEX  are  of  type  byte.  SJNDEX  indicates 
which  character  in  the  SOURCE  string  is  the  first  to  be  transcribed  to  the 
DJNDEX  position  in  the  DESTINATION  string. 


7.  Variables  and  Constants 

a.  Global 

No  global  variables  or  constants  are  used  by  STRING_COPY. 


b.  Internal  to  the  Module 

Beyond  the  input  and  output  parameters,  STRING_COPY  uses  no 
module  level  variables.  The  module  constant  END  OF  STRING,  value  7C  hex 
the  ASCII  character  is  used  to  indicate  end  of  string. 


c.  Internal  to  the  Routine 

STRING_COPY  uses  no  routine  level  variables  or  constants. 


8.  Other  Routines  Called 

STRING  COPY  calls  no  other  routines. 


9.  Output  of  Routing 

Upon  the  completion  of  STRING_COPY  the  contents  of  the  source 
string  has  been  copied  to  the  destination  string. 

10 Routine  Flaws 

STRING_COPY  is  completely  acceptable  in  its  current  form. 


11.  Reference  to  Listing 

STRING_COPY's  program  listing  is  on  page  374  in  Appendix  F. 
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1 .  Routine  Name:  ASCII 

2.  Internal  routine  of  Collect_Data  Module 

3.  Written  in  PL 2;  28  lines  of  code. 


4.  Synopsis  of  Routine 

ASCII  takes  value  and  translates  it  into  a  string  of  ASCII  characters 
that  represents  the  value.  Also  input  to  ASCII  is  the  base  of  desired  representa¬ 
tion.  Thus  ASCII  can  be  used  to  translate  the  input  value  into  binary,  decimal,  or 
hexidecimal  strings.  This  ASCII  routine  of  Collect_Data  Module  is  a  combination 
of  the  ASCII  and  PLACE_LOOP  routines  of  Enhancements  Module.  The  differ¬ 
ence  between  this  ASCII  and  the  combination  of  the  Enhancements  Module  rou¬ 
tines  is  that  ASCII  puts  the  individual  characters  into  an  string  where  the  En¬ 
hancements  Module  combination  writes  each  individual  character  to  a  desired 
logical  unit. 

ASCII  accomplishes  its  task  with  a  loop  and  a  large  Case  statement. 
The  loop  steps  through  each  place  of  the  output  representation,  beginning  with 
the  most  significant  place.  For  example,  if  the  number  274  was  to  be  represen¬ 
ted  in  decimal,  the  first  place  to  be  checked  would  be  the  100’s.  The  contribution 
of  each  place  to  the  total  value  is  determined  and  translated  into  a  character  by  a 
sixteen  possibility  ("0"  to  "9"  and  "A"  to  "F)  Case  statement  and  the  character  is 
placed  in  the  output  string.  If  the  contribution  is  outside  the  define  characters,  a 
"?"  is  placed  in  the  output  character  string.  The  loop  then  drops  to  the  next  signi¬ 
ficant  character  (or  place)  and  determines  the  next  contribution.  The  looping 
continues  until  the  I's  place  has  been  determined.  The  return  ends  by  placing  a 
carriage  return  on  the  end  of  the  string  of  characters. 

5.  Routine  Relationship  Diagram 


CREATE  DATA  FILE 


ASCII 


Figure  61 .  Relationship  of  ASCII  and  CREATE_DATA_FILE 
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ASCII  is  called  only  by  CREATE_DATA_FILE  and  is  invoked  with 

CHANNEL  ASCII(  WORD(  INPUT_CHANNEL),  10.  10,  CHANNEL  ) 

which  corresponds  to  the  ASCII  parameter  definitions 

TEXT_STRING  ASCII(  NUMBER,  INDEX,  DIVISOR,  INPOINTER  ) 

TEXT_STRING  and  INPOINTER  are  of  type  ASCII_PTR  (or  pointer  to  ASCII 
string)  and  NUMBER,  INDEX,  and  DIVISOR  are  of  type  Word.  INPOINTERA[0] 
passes  in  the  starting  location  of  the  output  string.  Strictly  speaking,  the  return 
parameter  TEXT_STRING  isn't  necessary.  It  was  included  to  make  clear  the  out¬ 
put  of  the  routine.  NUMBER  is  the  value  to  be  translated  into  its  character  string 
representation.  DIVISOR  is  the  base  of  the  representation,  and  INDEX  is  DIVI¬ 
SOR  raised  to  the  highest  anticipated  factor. 


Two  locally  defined  variables,  VALUE  and  POINT,  are  used  by  ASCII. 
VALUE,  of  type  Word,  holds  the  value  contributed  to  NUMBER  by  each  place  of 
the  character  string  representation.  VALUE  is  obtained  by  integer  division  of 
NUMBER  by  INDEX.  POINT,  of  type  Byte,  is  a  place  keeper  for  the  current  loca¬ 
tion  in  the  output  TEXT_STRING.  POINT  is  incrimented  for  each  character  or 
place. 

ASCII  uses  one  constant,  CARRIAGE_RETURN,  to  represent  the 
ASCII  carriage  return  (value  0D  hex). 


ASCII  calls  no  other  routines. 


At  the  end  of  ASCII,  TEXT_STRING  is  filled  with  the  characters  that 
represent  the  value  of  NUMBER  in  base  DIVISOR. 
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1.  Routine  Name:  GET_DATE 

2.  Internal  routine  of  Collect_Data  Module 

3.  Written  in  PLZ;  10  lines  of  code. 


4.  Synopsis  of  Routine 

Procedure  GET_DATE  interfaces  Collect_Data  Module  with  the  Utility  Mod¬ 
ule,  asembly  language  routine  DATE.  DATE  obtains  the  current  system  date  from 
its  storage  location  in  memory  and  passes  back  six  Byte  valued,  the  six  chara¬ 
cters  representing  the  day,  month,  and  year.  GET_DATE  takes  these  six  chara¬ 
cters  and  places  them  into  a  single  ASCII  string.  The  releationships  of  these  rou¬ 
tines  is  shown  in  the  figure  below. 


5.  Routine  Relationship  Diagram 


SAMPLE  DATA 


(  TODAYS.DATE  ^ — 

GET_DATE 

System  Memory 

DA 

LU 

•Utility  Module* 


Figure  62.  Relationship  of  GET_DATE  to  SAMPLE_DATA  and  DATE. 
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GET_DATE  is  called  only  by  SAMPLE_DATA  and  is  invoked  with 

TODAYS_DATE  :=  GET_DATE(  IN_POINTER  ) 

where  both  TODAYS_DATE  and  IN_POINTER  are  both  of  type  ASCII_PTR  for 
pointer  to  ASCII  string.  The  output  parameter  TODAYS_DATE  isn't  really  neces¬ 
sary  as  IN_  POINTER  supplies  all  the  information  necessary  for  GETJDATE  to 
load  the  character  string.  TODAYS_DATE  was  included  to  make  clear  the  output 
of  the  routine. 


7.  Variables  and  Constants 

GET_DATE  uses  six  local  Byte  valued  variables.  These  six  variables, 
YEAR1,  YEAR2,  MONTH1,  MONTH2,  DAY1,  and  DAY2  are  used  for  the  return 
parameters  in  the  call  to  the  external  routine  DATE.  GET_DATE  uses  one  mod¬ 
ule  level  constant,  CARRIAGEJRETURN,  of  value  0D  hex. 


gT  Other  Routings  Called 

GET_DATE  calls  DATE,  and  external  routine  of  the  Utility  Module,  to 
get  the  six  characters  of  the  system  date.  DATE  is  invoked  with 

YEAR1 ,  YEAR2,  MONTH1 ,  MONTH2,  DAY1 ,  DAY2  :=  DATE 

where  each  of  the  six  output  parameters  are  of  typeByte  and  hold  an  ASCII 
character. 


9,  Output  of  Routine 

GET_DATE  results  in  the  text  string  TODAYS_DATE  begin  filled  with 
the  six  characters  of  the  system  date,  ending  with  a  seventh  character,  a  carriage 
return. 


iQ-  Pgvt'ng  flaws 

GET_DATE 's  current  implementation  is  acceptable. 
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1.  Routine  Name:  FIND_TIME_CNST 

2.  Internal  routine  of  Collect_Data  Module. 

3.  Written  in  PL Z;  5  lines  of  code. 


4.  Synopsis  of  Routine 

This  little  routine  is  used  to  more  accurately  find  the  CTC  program¬ 
ming  time  constant.  Normally,  division  in  PLZ  produces  a  truncated  result  rather 
than  the  more  accurate  rounded  result  (Ref  6:  43).  FIND_TIME_CNST,  via  an 
intermediate  term  and  modulo  division,  determines  whether  the  best  time  con¬ 
stant  is  the  truncated  division  (equivalent  to  rounding  down)  or  should  be  incre¬ 
mented  by  one  (equivalent  to  rounding  up).  The  rounded  TIME_CNST  is  then 
returned  to  the  calling  routine  FIND_CTC_COMMANDS. 


5.  Routine  Relationship  Diagram 


FIND_CTCJ 

COMMANDS 

FIND_TIME_CNST 

Figure  63.  Relationship  of  FIND_TIME_CNST  to 
FIND_CTC_COMMANDS 


6,  invocation 

This  routine  is  invoked  from  FIND_CTC_CMDS  with 

TIME_CNST  :=  F1ND_TIME_CNST(  TIME,  MULTIPLER,  DIVISOR  ) 

where  the  input  parameters  are  all  of  type  Word  and  the  output  parameter  is  of 
type  Byte.  TIME  corresponds  to  Period_Desired,  MULTIPLER  corresponds  to 
Clock_Rate,  and  DIVISOR  corresponds  to  Prescale_Counter.  FIND_CTC_COM- 
MANDS  is  carefull  not  to  pass  to  FIND_TIME_CNST  input  parameters  which 
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v> 


would  cause  overflow. 


and  Cons 


FIND_TIME_CNST  uses  one  internal  variable,  INTERMEDIATE,  of 
type  Word.  INTERMEDIATE  holds  the  product  of  the  Period_Desired  and  the 
Clock  Rate. 


FIND  TIME  CNST  calls  no  other  routines. 


FIND_TIME_CNST  passes  back  to  FIND_CTC_COMMANDS  the  time 
constant  required  to  achieve  the  desired  timing  period  given  the  CTC  prescale 
counter  value. 


FIND_TIME_CNST  is  acceptable  though  it  perhaps  should  be  named 
ROUNDING_DIVISION  to  better  reflect  its  basic  function  rather  than  its  employ¬ 
ment. 


The  listing  of  FIND_TIME_CNSPs  code  is  on  page  376  in  Appendix 
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1.  Routine  Name:  F1ND_CTC_C0MMANDS 

2.  Internal  routine  of  Collect_Data  Module. 

3.  Written  in  PL Z;  35  lines  of  code. 


4.  Synopsis  of  Routine 

This  routine  determines  the  values  of  the  three  parameters  required  to 
establish  the  desired  sampling  interval.  Two  parameters  are  needed  to  program 
the  Counter  Timer  Chip  (CTC)  which  issues  periodic  interrupts,  the  prescale 
counter  and  the  time  constant  (Ref  7:  Sec  3.7).  One  parameter  is  required  for  the 
additional  sixteen  bit  down  counter  used  for  longer  sampling  intervals.  FIND_ 
CTC_COMMANDS  uses  FIND_TIME__CNST  to  determine  the  CTC  time  constant. 
The  overall  formula  for  the  sampling  interval  is 

Sampling  Period  ■ 

Clock_Period  X  Prescale_Counter  X  Time_Constant  X  Counter 

where 

CIock_Period  *  0.4072  microseconds, 

Prescale_Counter  a  16  or  256, 

Time_Constant  *  .  0  to  255,  and 

Counter  =  1  to  65535. 

Since  the  user  selectes  the  sampling  period  and  the  clock  period  is  fixed,  the 
three  variable  parameters  available  to  FIND_CTC_COMMANDS  are  the  prescale 
counter,  time  constant,  and  counter  value.  As  discussed  in  the  introduction  to  the 
Sampler  Module,  the  timing  periods  have  been  divided  into  four  ranges.  Figure 
64  below  (a  duplicate  of  the  Sampler  Module  figure)  shows  the  ranges.  Within 
these  ranges  the  Prescale_Factor  is  fixed;  within  the  longest  two  ranges  the 
Time_Constant  is  also  fixed.  The  sampling  period  ranges  and  the  values  of  the 
variable  parameters  are 


Sampling  Period  Range  Prescale  Value 

Time  Constant 

CTC  Period 

-Counter 

minimum  to  1 .0  msec 

16 

variable 

variable 

not  used 

1.0  msec  to  10.0  msec 

256 

variable 

variable 

not  used 

10.0  msec  to  1.0  sec 

16 

154 

1  msec 

variable 

1 .0  sec  to  maximum  period 

256 

240 

25  msec 

variable 

For  the  first  two  ranges,  only  the  CTC  Time_Constant  needs  to  be  de¬ 
termined  as  the  counter  isn't  used.  The  time  constant  is  a  counter  used  by  the 
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CTC.  In  advance  of  the  time  constant  counter  is  a  prescale  counter  of  either  1 6 
or  256  which  correspond  to  the  "fast  mode"  and  "slow  mode."  Given  the  MCB 
clock  rate  of  2.547  Mhz  the  timing  constant  is  found  with  (Ref  7:  Sec  3.7) 

Time_Constant  =  (  Period_Desired  X  Clock_Rate  )  /  Prescale_Counter 

The  time  constants  are  found  by  calling  FIND_TIME_CNST,  a  routine  which 
performs  rounding  division  rather  than  the  standard  PLZ  trucating  division. 
Depending  upon  the  time  period  desired,  one  of  four  calls  to  FIND_TIME_CNST 
is  used.  These  calls  are  discussed  later. 


Counter/Timer  Combinations  Used  for  Real  Time  Clock 


Slow  Timer  &  16  Bit  Counter! 
( TC_SAMPLE ) 


Timing  Period  in  Seconds 
10 

I 


Fast  Timer  &  16  Bit  Counter 
( TC_SAMPLE ) 


Slow  Timer  Only 
(TO_SAMPLE 


Fast  Timer  Only 
(TO  SAMPLE) 

I 


29.3  Minutes 


Full  Range  of 
Timer  Combination 


Employed  Range  of 
Timer  Combination 


6.515  pSec 


1.688  mSec 


Figure  64.  Counter/Timer  Combinations  Used  for  Real  Time  Clock 
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For  the  longer  timing  periods,  the  CTC  timing  is  fixed  and  only  the 
counter  value  is  used  to  set  the  timing  period.  The  formula  used  is 

Counter  :=  Period_Desired  /  CTC_Period 

where  CTC_Period  is  either  1  msec  or  25  msec.  In  the  code  implementation, 
multiplication  by  the  inverse  of  the  CTC  period,  with  adjustments  for  period  units, 
is  used. 

Having  determined  the  CTC_MODE,  the  CTC_TIME_CONSTANT, 
and  the  COUNT  for  the  counter,  FIND_CTC_COMMANDS  ends. 


5.  Routine  Relationship  Diagram 


Figure  65.  Relationship  Between  FIND_CTC_COMMANDS  and 
PREPARE  COLLECTER  and  FIND  TIME  CNST 


6,  Invocation 

FIND_CTC_COMMANDS  is  invoked  from  PREPARE_COLLECTER 
via 

ERROR_CODE,  CTC_MODE, 

CTC_TIME_CONSTANT,  COUNT  := 

FIND_CTC_COMMANDS(  TIME,  UNITS  ) 

where  TIME  is  the  desired  sampling  interval  measured  in  UNITS,  both  input  para¬ 
meters  being  type  Integer.  The  output  parameter  ERROR_CODE,  type  Byte,  re¬ 
turns  an  error  message  if  an  out  of  range  sampling  period  was  requested.  CTC_ 
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MODE,  type  Byte,  returns  the  CTC  command  for  "slow  mode"  (interrupting,  pre¬ 
scale  factor  of  16)  or  "fast  mode"  (interrupting,  prescale  factor  of  256).  CTC_ 
TIME_  CONSTANT,  type  Byte,  returns  a  value  between  0  and  255,  for  the  CTC 
counter  (counter  range  1  to  256).  COUNT,  type  Word,  passes  back  the  additional 
counter  value  required  for  longer  sampling  periods.  COUNT  has  a  defined  range 
of  0  (signaling  no  counter  is  required)  to  65535. 


7,  Variables  and  Constants 


FIND_CTC_COMMANDS  uses  no  variables  beyond  the  input  and 
output  parameters  discussed  above.  The  routine  makes  use  of  several  module 
constants.  Their  names,  values,  and  purposes  are 


Constant 

Value 

Puroose 

MICRO_SECONDS 

-6  dec 

UNITS  input  to  indicate  units  of  TIME  input. 

MILLI_SECONDS 

-3  dec 

UNITS  input  to  indicate  units  of  TIME  input. 

SECONDS 

0  dec 

UNITS  input  to  indicate  units  of  TIME  input. 

MINIMUM_TIME 

50  dec 

Minimum  allowed  microseconds  for 
sampling. 

PERIOD_RANGE_ERROR 

El  hex 

Message  for  Out  of  Range  Sampling  Interval 

FAST_MODE 

87  hex 

CTC  command  for  interrupting  timer  with  a 
prescale  factor  of  1 6. 

SLOW_MODE 

A7  hex 

CTC  command  for  interrupting  timer  with  a 
prescale  factor  of  256. 

The  MINIMUM_TIME  of  50  microseconds  was  selected  to  allow  the  AIO  analog  to 
digital  converter  to  settle  and  allow  for  the  interrupt  service  routine  cycling. 


8.  Other  Routines  Called 

FIND_CTC_COMMANDS  calls  FIND_TIME_CNST  to  determine  the 
TIME_CNST.  FIND_TIME_CNST  is  used  because  it  performs  a  rounding  divi¬ 
sion  rather  than  PLZ's  standard  trucation  division.  FIND__CTC_COMMANDS 
contains  four  calls  to  FIND  TIME  CNST  all  of  the  form 
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TIME_CNST  :=  FIND_TIME_CNST (  TIME,  MULTIPLER,  DIVISOR ) 

Both  MULTIPLER  and  DIVISOR  are  passed  to  FIND_TIME_CNST  as  constants 
using  different  constants  for  each  of  the  four  calls.  The  timer  periods,  constants, 
and  units  of  TIME  used  are 

Sampling  Range _  TIME  Units  MULTIPLER  DIVISOR 


mimimum 

to 

26  psec 

microseconds 

2457 

16000 

26  psec 

to 

266  psec 

microseconds 

246 

1600 

226  psec 

to 

999  psec 

microseconds 

25 

160 

1  msec 

to 

9  msec 

milliseconds 

2457 

256 

The  values  passed  with  MULTIPLER  and  DIVISOR  are  selected  to  keep  FIND_ 
TIME_CNST  from  having  a  multiply  overflow  and  maintain  the  maximum  accur¬ 
acy  possible. 


9.  Output  of  Routine 

At  the  end  of  FIND_CTC_COMMANDS,  the  three  parameters  neces¬ 
sary  to  program  the  CTC  and  set  up  the  down  counter  have  been  determined. 
However,  if  an  out  of  range  sampling  period  was  requested,  and  error  code  will 
be  returned  to  the  PREPARE  COLLECTER. 


ilQ_RQUtin8  Flaws 

The  code  and  organization  of  FIND_CTC_COMMANDS  is  acceptable 
with  one  exception.  ERROR_CODE  needs  to  be  set  to  FALSE  as  the  first  execu¬ 
table  statement.  The  comment  lines  in  the  code  need  improvement  though. 


11.  Reference  to  Listing 

The  program  listing  of  FIND_CTC_COMMANDS  is  on  page  377  -378 
in  Appendix  F. 
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1.  Routine  Name:  SIZE_DATA_BUFFER 

2.  Internal  routine  of  Collect  Data  Module. 


3.  Written  in  PLZ;  10  lines  of  code. 


This  routine  is  largely  a  place  keeper,  intended  to  be  replaced  by  a 
routine  which  calls  the  Utility  Module  routine  ALLOCATE.  SIZE_DATA_BUFFER 
compairs  the  number  of  samples  requested  by  the  user  with  the  storage  supplied 
by  Buffers  Module.  If  the  number  of  samples  is  less  than  1000  decimal,  then  all 
is  ok  and  the  routine  will  proceed.  Otherwise,  SIZE_DATA_BUFFER  will  output 
an  error  message  to  indicate  that  too  many  samples  were  requested. 

Ultimately,  this  SIZE_DATA_BUFFFER  would  be  replaced  with  a  rou¬ 
tine  which  calls  ALLOCATE,  an  assembly  language  routine  which  gives  PLZ  pro¬ 
grams  access  to  the  RIO  operating  system  memory  manager.  Though  ALLO¬ 
CATE,  this  "new"  S IZE_DAT A_BU FFE R  could  make  a  real  time  request  for  data 
storage  and  not  be  limited  to  preformated  buffers. 


Figure  66.  Relationship  Between  SIZE_DATA_BUFFER  and 
PREPARE  COLLECTOR 


SIZE  DATA  BUFFFER  is  invoked  from  PREPARE  COLLECTER  via 
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ERROR.CODE,  SAMPLES_ALLOWED  := 

SIZE_DATA_BUFFER(  SAMPLES_REQUESTED ) 

where  SAMPLES_REQUESTED  and  SAMP LES_ALLO WED  are  of  type  Word 
and  ERROR_CODE  is  of  type  Byte. 


SIZE_DATA  .BUFFER  uses  the  globally  defined  DATA.BUFFER  to 
determine  how  much  storage  area  is  available.  The  routine  uses  no  global 
constants. 


b.  Module  Level 

SIZE_DATA_BUFFER  uses  no  module  level  variables.  SIZE_DATA_ 
BUFFER  uses  three  module  level  constants  to  define  error  codes  and  give  the 
highest  possible  address  for  data  in  the  buffer.  FALSE  (value  00  hex)  is  the 
error  code  for  no  errors  occured.  TOO_MANY_$AMPLES  (value  E0  hex)  is  the 
error  code  output  when  the  number  of  samples  requested  by  the  user  exceeds 
AVALIABLE.WORDS.  MAX.  BUFFER.ADDRESS  is  set  to  a  high  memory  value 
(9A00  hex),  above  the  code  of  all  the  modules  of  the  data  collection  system  but 
below  the  system  stack.  This  is  used  in  conjunction  with  the  beginning  address 
of  DATA.BUFFER  to  determine  how  much  space  is  available  for  data  storage 
(above  the  define  range  of  DATA.BUFFER.  This  is  a  cludge;  a  call  to  ALLOCATE 
would  be  far  superior. 


c.  Routine  Level 

SIZE.DATA.BUFFER  uses  a  single,  routine  level  variable  AVAIL- 
ABLE.WORDS  to  hold  the  number  of  words  (one  word  is  two  bytes)  available  for 
data  storage. 


This  version  of  SIZE.DATA.BUFFER  calls  no  other  routines.  An 
improved  SIZE.DATA.BUFFER  would  call  ALLOCATE. 
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If  the  number  of  samples  requested  by  the  user  does  not  exceed  the 
storage  available,  S IZE_D ATA_B U FFE R  will  return  ERROR_CODE  as  FALSE 
and  SAMPLES_  ALLOWED  as  the  number  of  samples  requested.  However,  if 
too  many  samples  are  requested,  ERROR_CODE  will  be  returned  as  TOO_ 
MANY.SAMPLES  and  SAMPLES_ALLOWED  will  be  set  to  AVAILABLE. 
WORDS. 


SIZE_DATA_BUFFER  is  ok,  but  the  function  it  performs  would  be  far 
better  served  by  calling  ALLOCATE.  That  Utility  Module  routine  would  allow 
SIZE_DATA_  BUFFER  to  interact  with  the  operating  system  memory  manager. 


The  listing  of  SIZE_DATA_BUFFER  can  be  found  on  page  379  in 
Appendix  F. 
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1.  Routine  Name:  ERROR_IN_PREPARE 

2.  Internal  routine  of  Collect_Data  Module 

3.  Written  in  PL 2;  14  lines  of  code. 


4.  Svnoosis  of  Routine 

ERRORJN_PREPARE  writes  error  message  to  the  system  console  if 
an  error  code  other  than  FALSE  is  returned  by  any  of  the  routines  under  PRE- 
PARE_COLLECTER.  Two  error  messages  are  possible.  If  TOO_MANY_SAM- 
PLES  is  returned  by  SIZE_DATA_BUFFER,  a  message  is  written  to  the  console 
identifying  how  many  samples  will  be  collected.  If  PERIOD_RANGE_ERROR  is 
returned  by  FIND_CTC_  COMMANDS,  the  defined  ranges  will  be  written  to  the 
console  and  ERROR  MESSAGE  will  be  reset  to  FATAL. 


5.  Routine  Relationship  Diagram 


Figure  67.  Relationship  of  ERROR_IN_PREPARE  to  Its  Calling 
and  Subordinate  Routines. 


6.  Invocation 

ERROR_IN_PREPARE  is  called  from  P RE PARE_COLLECTE R  with 
OUT_ERROR_CODE  :=  ERROR_IN_PREPARE(  IN_ERROR_CODE  ) 
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where  both  the  input  and  output  parameters  are  of  type  Byte. 


7.  Variables  and  Constants 

ERROR_IN_PREPARE  uses  no  variables.  It  uses  four  constants, 
TOO_MANY_  SAMPLES,  PERIOD  JRANGE.ERROR,  FALSE,  and  FATAL  which 
are  the  possible  error  codes  within  PREPARE_COLLECTER  and  its  subrodinate 
routines.  The  values  of  these  module  level  constants  are  E0  hex,  El  hex,  00 
hex,  and  FE  hex  respectively. 


8.  Other  Routines  Called 

ERROR_IN_PREPARE  calls  three  external  routines,  WRITE,  WRITE_ 
DWORD,  and  WRITELN,  all  of  the  Enhancements  Module.  These  three  routines 
are  used  to  output  text  strings  and  decimal  values  to  the  system  console.  The 
routines  are  invoked  with 

WRITE(  LOGICALJJNIT,  Pointer-to-Text-String ) 

WRITE_DWORD(  LOGICALJJNIT,  NUMBER ) 

WRITELN(  LOGICALJJNIT,  Pointer-to-Text-String ) 

where  LOGICALJJNIT  is  of  type  Byte  and  NUMBER  is  of  type  Word.  In  ERROR_ 
IN_PREPARE  LOGICALJJNIT  is  all  ways  passed  as  the  constant  CONSOLE_ 
OUT.  Pointer-to-Text-String  could  be  a  variable  of  type  ASCII_PTR  or  could  be 
a  constant  string.  In  ERRORJN_PREPARE  the  constant  string  form  is  used. 
NUMBER  is  a  sixteen  bit  value  which  WRITE_DWORD  will  translate  into  the 
ASCII  characters  of  its  base  10  representation.  WRITE  and  WRITE JDWORD  do 
not  output  carriage  returns  at  the  end  of  their  output;  WRITELN  does. 


9.  Output  of  Routine 

The  output  of  ERRORJN_PREPARE  are  messages  to  the  system  con¬ 
sole  which  tell  the  user  that  the  input  parameters  provided  are  out  of  range.  If  the 
error  was  an  out  of  range  sampling  period,  ERRORJN_PREPARE  returns  to 
PREPARE.  COLLECTER  the  FATAL  error  code.  Otherwise  the  FALSE  error 
code  is  returned. 
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ERROR_IN_PREPARE's  error  message  to  the  system  console  is 
wrong.  It  lists  the  mimimum  time  range  as  7  nsec;  50  nsec  is  the  correct  value. 
Also,  PREPARE_COLLECTER  calls  ERROR_IN_PREPARE  only  when  errors 
occur.  The  alternate  structure  of  having  ERROR_IN_PREPARE  determine 
whether  an  error  has  occured  would  be  superior. 


11.  Reference  lo  Listing 

ERROR_IN_PREPARE's  listing  is  on  page  380  in  Appendix  F. 
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1.  Routine  Name:  PREPARE  COLLECTER 


2.  Primary  subordinate  routine  of  Collect_Data  Module 


3.  Written  in  PLZ;  13  lines  of  code. 


4.  Synopsis  of  Routine 

PREPARE_COLLECTOR  is  the  second  routine  called  by  SAMPLE^ 
DATA,  the  executive  routine  of  Collect_Data  Module.  PREPARE_COLLECTER 
takes  the  user  supplied  sampling  instructions  and  translates  them  into  the  CTC 
commands  and  other  parameters  needed  by  Sample_Data.  As  shown  in  the 
figure  below,  PREPARE_COLLECTOR  accomplishes  its  functions  through  calls 
to  three  subordinate  routines,  FIND_CTC_COMMANDS,  SIZE_DATA_BUFFER, 
and  ERROR_IN_PREPARE.  The  last  routine  is  the  error  service  routine  for  PRE- 
PARE_COLLECTER. 

PREPARE_COLLECTOR  is  rather  simple  in  implementation,  consist* 
ing  of  one  do  loop.  Within  the  loop,  FIND_CTC  COMMANDS  is  called  followed 
immediately  by  ERROR_IN_PREPARE  to  see  if“ FIND_CTC_COMMANDS  suc¬ 
cessfully  executed.  If  an  error  is  detected,  the  output  error  code  is  loaded,  the  do 
loop  is  exited,  and  PREPARE_  COLLECTOR  ends.  If  no  error  occured,  SIZE__ 
DATA_BUFFER  is  called,  again  followed  immediately  by  ERROR_IN_PREPARE. 
If  an  error  is  detected,  th  output  error  code  is  loaded,  the  do  loop  is  exited,  and 
PREPARE_COLLECTOR  ends.  If  no  error  was  detected,  the  do  loop  is  exited 
and  PREPARE_COLLECTOR  ends.  The  do  loop  is  executed  only  once. 
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Figure  68.  Relationship  of  PREPARE_COLLECTOR  to  SAMPLE_DATA  and  its 

Subordinate  Routines. 


PREPARE_COLLECTOR  is  invoked  from  SAMPLE_DATA  with 

ERROR_CODE, 

CTC_MODE, 

TIME_CONSTANT, 

DOWN_COUNT, 

NUMBER_OF_SAMPLES  =: 

PREPARE_COLLECTOR(  PERIOD_VALUE, 

PERIODJJNITS, 

SAMPLES_REQUESTED ) 

where  these  parameters  are  of  the  following  type  and  purpose. 
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input  parameters  — 


PERIOD_VALUE  Integer 

PERIOD_UNITS  Integer 


SAMPLES  REQUESTED  Word 


The  desired  time  duration  of  the 
sampling  period  in  PERIODJJNITS 
units. 

The  designated  units  of  PERIOD_ 
VALUE.  The  possible  values  are  three 
constants  MICRO_SECONDS,  MILLI_ 
SECONDS,  and  SECONDS. 

The  number  of  analog  to  digital  con- 
verisons  the  user  wants  collected  and 
stored. 


output  parameters - 


ERROR_CODE  Byte 


CTC_MODE  Byte 


TIME_CONSTANT  Byte 


DOWN  COUNT  Word 


NUMBER  OF  SAMPLES  Word 


A  code  to  tell  SAMPLE_DATA  how 
things  went  within  PREPARE_COL- 
LECTOR.  Two  values  are  possible,  the 
constants  FATAL  and  FALSE. 

The  first  of  two  commands  to  the  CTC  to 
program  its  interrupts.  CTC_MODE  has 
two  possible  values  SLOW_MODE  and 
FAST_MODE. 

The  second  CTC  programming  com¬ 
mand.  It  tells  the  CTC  how  many  times 
to  count  before  interrupting.  Values  of 
0  to  255  are  possible  with  0  meaning 
to  count  256  times. 

The  number  of  interrupts  the  down 
counter  (used  longer  sampling  periods) 
must  receive  before  commanding  the 
AIO  board  to  initiate  an  A  to  D 
conversion. 

The  number  of  samples  to  be  collected. 
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PREPARE_COLLECTOR  uses  no  variables  beyond  the  input  and  out¬ 
put  parameters  discussed  above.  PREPARE_COLLECTOR  uses  two  module 
level  constants,  FATAL  and  FALSE,  as  error  codes.  Values:  FE  hex  and  00  hex. 


8.  Other  Routines  Called 

PREPARE_COLLECTER,  as  shown  in  the  figure  above,  calls  three 
subordinate  routines  FIND_CTC_COMMANDS,  NUMBER  _OF_SAMPLES,  and 
ERROR_  IN_PREPARE.  Their  invocation  statements  follow. 

ERROR_CODE,  CTC_MODE,  TIME_CONSTANT,  DOWN_COUNT  := 

FIND_CTC_COMMANDS(  PERIOD_VALUE,  PERIODJJNITS ) 

ERROR_CODE,  NUMBER_OF_SAMPLES  := 

SIZE_DATA_BUFFER(  SAMPLES_REQUESTED ) 

ERROR_CODE  :=  ERRORJN_PREPARE(  ERROR_CODE  ) 

Please  consult  the  descriptions  of  these  routines  for  more  details. 


9,  -Qutput  flf  Routine 

There  are  two  sets  of  possible  outputs  for  PREPARE_COLLECTOR.  If 
something  went  seriously  wrong,  PREPARE_COLLECTOR  will  return  the  FATAL 
error  code.  This  will  cause  termination  of  SAMPLE_DATA.  If  nothing  went  seri¬ 
ously  wrong,  PREPARE_COLLECTER  will  return  a  FALSE  error  code  and  the 
programming  values  for  the  CTC,  down-counter,  and  the  number  of  samples  to 
be  collected. 


1  (^Routine  Flaws 

As  it  stands  PREPARE_COLLECTOR  is  ok.  It  might  be  better  to  call  a 
modified  ERROR_  IN_PREPARE  after  each  subroutine  call  and  then  check  the  re¬ 
turned  error  code. 


11.  Reference  to  Listing 

The  listing  of  PREPARE_COLLECTER’s  code  is  on  page  381  in 
Appendix  F. 
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1.  Routine  Name:  ERROR_IN_CREATE 

2.  Subrodinate  routine  of  Collect_Data  Module. 

3.  Written  in  PLZ;  16  lines  of  code. 


4.  Svnoosis  of  Routine 

ERROR_!N_CREATE  is  one  of  the  support  routines  for  CREATE_ 
DATA_FILE.  This  routine  checks  the  error  code  generated  during  CREATE_ 
DATA_FILE,  outputs  messages  to  the  system  console  based  on  the  error  codes, 
and  sets  the  final  error  code.  As  ERROR_IN_CREATE  is  called  only  if  a  FATAL 
error  occurs,  invocation  of  this  routine  signals  termination  of  Collect_Data 
Module  execution. 


5.  Routine  Relationship  Diagram 


Figure  69.  Relationship  of  ERROR_IN_CREATE  to  its  Calling 
Routine  and  Subordinate  Routines. 


6.  Invocation 

ERROR_IN_CREATE  is  invoked  from  C REATE_DAT A_FI LE  with 
OUT_ERROR_CODE  := 

ERROR_IN_CREATE(  IN_ERROR_CODE,  RETURN_CODE  ) 
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where  all  three  parameters  are  of  type  Byte. 


7.  Variables  and  Constants 

ERROR_IN_CREATE  uses  no  variables  other  than  the  input  and 
output  parameters.  Several  module  level  constants  are  used.  Their  names, 
values,  and  definitions  are 


Constant  Name 

Value 

Definition 

BAD_CHARACTER 

BC  hex 

Error  code  for  invalid  character  in  a  file 
name  string.  See  VALIDJ5TRING. 

CONSOLE JDUT 

02  hex 

The  logical  unit  number  for  the  monitor 
screen. 

FATAL 

FE  hex 

Error  code  for  fatal  error. 

DUPLICATE J=ILE 

D0  hex 

RIO  return  code  for  duplicate  file  name. 

9.  Other  Routines  Called 

ERROR_IN_CREATE  calls  two  of  the  output  routines  of  Enhancements 
Module  to  write  messages  to  the  system  console.  The  routines  called  and  their 
invocations  are 

WRITE LN(  LOGICALJJNIT,  Pointer-To-Text-String  ) 

WRITE_RCODE(  LOGICALJJNIT,  RETURN_CODE ) 

where  LOGICALJJNIT  (type  Byte)  is  the  number  of  the  logical  unit  to  be  written 
to,  Pointer-to-Text-String  (type  ASCII_PTR)  points  to  the  output  text  or  is  a  con¬ 
stant  text  string,  and  RETURN  JSODE  (type  Byte)  is  the  completion  code  passed 
back  from  calls  to  the  RIO  Operating  System.  WRITLEN  outputs  a  string  of  text 
followed  by  a  carriage  return  to  the  designated  logical  unit.  WRITE_RCODE  out¬ 
puts  the  text  translation  of  the  RIO  return  codes  to  the  designated  logical  unit. 
WRITE_RCODE  is  used  to  output  unexpected  RIO  return  codes. 


9.  Output  of  Routine 

ERRORJN_CREATE  writes  messages  and  operating  system  return 
codes  to  the  system  console.  In  its  current  form,  ERROR_IN_CREATE  always 
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returns  the  output  parameter  OUT_ERROR_CODE  as  FATAL. 


10.  Routine  Flaws 

ERRORJN_CREATE  would  be  improved  by  by  using  the  IF  state¬ 
ments  within  a  DO  loop  structure  like  that  used  in  PREPARE_COLLECTOR  or  the 
CASE  statement  structure  like  that  used  in  ERROR_IN_PREPARE.  Even  if  the 
structure  isn't  changed,  ERROR_IN_CREATE  needs  to  initially  set  ERROR_CODE 
to  FALSE. 


11.  Reference  to  Listing 

The  program  listing  of  ERROR_IN_CREATE  is  on  page  382  in 
Appendix  F. 
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1.  Routine  Name:  VALID_STRING 

2.  Subordinate  routine  of  Collect_Data  Module. 

3.  Written  in  PLZ;  10  lines  of  code. 


4,_S.ynQpsis.Ql_RQ.uliD3 

VALID_STRING  checks  the  content  of  a  text  string  passed  to  it  to  see 
whether  it  is  a  valid  file  name.  Specifically,  VALID_STRING  ensures  that  each 
character  in  the  string  is  a  0  through  9  or  a  A  through  Z.  This  check  is  accom¬ 
plished  by  examining  the  ASCII  value  of  each  character  against  the  ranges  de¬ 
fined  by  the  acceptable  characters.  Each  character  in  the  string  is  checked  until 
an  end  of  string  is  detected  or  32  characters  have  been  checked.  If  VALID_ 
STRING  finds  any  invalid  charactes,  the  output  ERROR_  CODE  is  set  to  BAD_ 
CHARACTER.  Otherwise  ERROR_CODE  is  returned  as  FALSE,  indicating  no 
error. 


5.  Routine  Relationship  Diagram 


CREATE J 

)ATA_FILE 

VALID_STRING 

Figure  70.  Relationship  of  VALID_STRING  to 
CREATE  DATA  FILE. 


6.  Invocation 

CREATE_DATA_FILE  calls  VALID_STRING  with 

ERROR_CODE  :=  VALID_STRING(  TEST_STRING  ) 

where  TEST_STRING  is  of  type  ASCII_PTR  (for  pointer  to  ASCII  string)  and 
ERROR_  CODE  is  of  type  Byte. 
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VALID_STRING  uses  one  internal  variable,  INDEX  (type  Byte),  in 
addition  to  the  input  and  output  variables.  INDEX  is  used  as  a  place  keeper  for 
the  string  TEST_STRING. 

VALID_STRING  uses  two  constants  FALSE  and  BAD_CHARACTER. 
FALSE,  value  00  hex,  is  the  error  code  for  every  thing  is  ok.  BAD_CHARACTER, 
value  BC  hex,  is  the  error  code  to  signal  that  a  invalid  character  was  found. 


8.  Other  Routines  Called 

VALID  STRING  calls  no  other  routines. 


9.  Output  of  Routine 

VALID_STRING  has  two  possible  outputs.  The  output  parameter 
OUT_  ERROR_CODE  is  either  FALSE  or  BAD_CHARACTER.  FALSE  if  no 
invalid  characters  were  found  in  the  string;  BAD_CHARACTER  if  one  invalid 
character  was  found. 


IQ,  Routing  Flaws 

VALID_STRING  is  acceptable,  though  its  listing  format  and  comments 
could  be  improved. 


11,  Reference  to  Listing 

The  listing  of  VAL!D_STRING's  code  is  on  page  383  in  Appendix  F. 
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1.  Routine  Name:  CREATE  DATA  FILE 


2.  Primary  subordinate  routine  of  Collect_Data  Module. 


3.  Written  in  PLZ;  29  lines  of  code. 


CREATE_DATA_FILE  is  the  third  routine  called  by  SAMPLE_DATA, 
the  executive  routine  of  Col!ect_Data  Module.  Using  instructions  passed  into 
Collect_Data  Module,  CREATE_DATA_FILE  opens  a  disk  file  into  which  the  data 
collected  by  Sampler  Module  will  be  transfered.  This  requires  the  formation  of  a 
valid  file  name  and  a  call  to  the  operating  system.  As  shown  in  the  figure  below, 
CREATE_  DATAJrILE  calls  many  routines  to  accomplish  these  functions. 


The  file  name  formed  has  three  fields  separated  by  periods.  The  first 
field  is  the  test  identifier,  passed  into  CREATE_DATAJFILE  from  the  user.  This 
field  is  six  characters  long  and  is  susposed  to  be  unique.  Routine  VALID_ 
STRING  is  called  to  ensure  the  user  input  has  only  valid  file  name  parameters.  If 
any  of  the  characters  are  invalid,  an  error  message  is  written  to  the  console  by 
E RROR _IN_C REATE  and  CREATE_DATA_FILE  ends  with  ERROR_CODE  being 
FATAL.  The  second  field  is  the  channel  number.  CREATE_DATA_FILE  is  pas- 
bsed  the  input  parameter  INPUT_  CHANNEL,  type  Byte.  The  routine  ASCII  is 
called  to  translate  INPUT_CHANNEL  into  the  ASCII  characters  that  are  the  base 
ten  representation  of  INPUT_CHANNEL.  The  third  field  is  the  phrase  "RAW_ 
DATA".  Thus  the  file  name  looks  like 


testid.##.RAW  DATA 


where  "testid"  is  the  unique  test  identifier  and  "##"  are  the  characters  that  repre¬ 
sent  the  input  channel  number. 


With  the  file  name  formed,  CREATE_DATA_FILE  calls  the  operating 
system  via  OPEN,  an  external  routine  of  the  PLZ.STREAM.IO  Module.  If  for  any 
reason  the  opening  is  not  successful,  an  error  message  is  writen  to  the  console 
by  ERROR_IN_  CREATE,  CREATE_DATA_FILE  ends,  and  ERROR_CODE  is 
returned  as  FATAL.  If  the  opening  is  successful,  CREATE_DATA_FILE  proceeds. 


With  the  data  file  open,  CREATE_DATA_FILE  continues  by  writing  into 
the  file  the  header  information.  Five  extenal  routines  of  the  Enhancements  Mod¬ 
ule  are  used  by  CREATE_DATA_FILE  to  write  the  header  information  to  the  disk 
file.  The  following  is  the  content  and  format  of  the  header. 

testid : testid 
|  i  n  p  u  t_c  h  a  n  n  e  I  '.channel 
|  peroid_value:  period  _value 
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|  p e ri o d_u n i ts  :  period_units 
|#_samples:  samples 
j#_samples:  samples 
j  date_of_test :  today s_date 
|user_message:  user_string 
jbeginning  of  d  a  t  a  :  1 1 

where  the  italized  items  are  the  names  of  the  text  string  variables.  Most  of  these 
text  string  variables  are  input  parameters  passed  into  CREATE_DATA_FILE. 
CHANNEL  is  formed  in  C RE ATE_D AT A_FI LE  through  the  call  to  ASCI!.  The  T 
character  (ASCII  C7  hex)  is  used  as  a  field  marker.  With  all  the  header  informa¬ 
tion  written  into  the  data  file,  CREATE_DATA_FILE  ends. 


SAMPLE  DATA 


CREATE  DATA  FILE 


ASCCII 


ERROR  IN  CREATE 


STRING  COPY 


VALID  STRING 


OPEN 


WRITE 


WRITE  HBYTE 


WRITE  HINTEGER 


WRITE  HWORD 


Figure  71.  Relationships  Between  CREATE_DATA_FILE,  SAMPLE_DATA,  and 

Subordinate  Routines. 
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6.  Invocation 

CREATE_DATA_FILE  is  invoked  from  SAMPEL_DATA  with 

ERROR_CODE  :=  CREATE_DAT A_FI LE(  INPUT_CHANNEL, 

DATA_FILE, 

PERIOD_VALUE, 

PERIOD_UNITS, 

SAMPLES,  TESTID, 
USER_MESSAGE, 
TODAYS.DATE  ) 

This  routine  has  many  input  parameters,  most  of  them  passed  in  to  become  part 
of  the  data  file  header.  Their  types  and  purposes  are 


Parameter  Name  Type  _ Definition 


INPUT_CHANNEL 

Byte 

The  number  of  the  analog  input 
channel,  1  to  16,  data  will  be  collected 
from. 

DATA_FILE 

Byte 

The  logical  unit  number  for  the  file. 

PERIOD_VALUE 

Integer 

The  desired  sampling  interval  (in 
PERIODJJNITS  units) 

PERIODJJNITS 

Integer 

The  units  of  PERIOD_VALUE.  The 
valid  values  are  MICROSECONDS, 
MILLISECONDS,  and  SECONDS. 

SAMPLES 

Word 

The  number  of  samples  to  be 
collected. 

TESTID 

ASCII_PTR 

A  pointer  to  a  six  character  (plus  car¬ 
riage  return)  string  that  is  the  unique 
test  identifier. 

USER_MESSAGE 

ASCII_PTR 

A  pointer  to  a  free  field  string  of 
characters. 

TODAYS_DATE 

ASCII_PTR 

A  pointer  to  a  six  character  string  (plus 
a  carriage  return)  that  represent  the 
date. 

The  single  output  parameter,  ERROR_CODE  (type  Byte),  passes  back  an  error 
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code  to  SAMPLE  DATA. 


7.  Variables  and  Constants 

CREATE_DATA_FILE  uses  several  internal  variables  in  addition  to 
the  parameters  discussed  above. 


Parameter  Name 


-lyos- 


Definition 


FILE_NAME_BUF 

ASCII.STRING 

A  32  character  buffer  to  hold  the 
completed  file  name.  19  characters 
are  used. 

CHANNELJ3UF 

ASCII_STRING 

A  32  character  buffer  to  hold  the 
completed  channel  number.  Only  3 
characters  are  used. 

FILE_NAME 

ASCII_PTR 

A  pointer  to  FILE_NAME_BUF. 

CHANNEL 

ASCII_PTR 

A  pointer  to  CHANNEL_BUF 

RETURN_CODE 

Byte 

Receives  the  operating  system  return 
code  from  the  call  to  OPEN. 

In  addition  to  these  variables,  CREATE_DATA_FILE  uses  two  con¬ 
stants,  OPERATION_COMPLETE  (value  80  hex)  and  FATAL  (value  FE  hex). 
OPERATION_  COMPLETE  is  the  RIO  Operating  System  return  code  for  all  went 
well.  FATAL  is  the  Colect_Data  Module  error  code  that  signals  fatal  errors. 


8.  Other  Routines  Called 

As  was  shown  in  the  figure  above,  CREATE_DATA_FILE  calls  ten 
routines.  Their  invocations  and  parameters  follow.  Unless  otherwise  stated,  the 
routines  are  part  of  Collect_Data  Module. 

a.  TEXT_STRING  :=  ASCII(  NUMBER,  INDEX,  DIVISOR,  INPOINTER) 

where  TEXT_STRING  and  INPOINTER  are  type  ASCII_PTR,  and  NUMBER, 
INDEX,  and  DIVISOR  are  type  Word.  ASCII  converts  NUMBER  into  the  string  of 
ASCII  characters  which  represent  it. 
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b.  STRING_COPY(  SOURCE,  SJNDEX,  DESTINATION,  DJNDEX  ) 

where  SOURCE  and  DESTINATION  are  type  ASCII_PTR,  and  SJNDEX  and 
DJNDEX  are  type  Byte.  STRING_COPY  transcribes  the  characters  of  SOURCE 
string  into  the  DESTINATION  string. 


c.  ERROR_CODE  :=  VALID_STRING(  TEST_STRING  ) 

where  ERROR_CODE  is  type  Byte  and  TEST_STRING  is  type  ASCII_PTR. 
VALID_  STRING  ensures  the  characters  in  TEST_STRING  are  valid  for  inclusion 
in  a  file  name. 


d.  RETURN_CODE  :=  OPEN(  LOGICAL_UNIT,  FILE_NAME_PTR,  MODE  ) 

where  RETURN_CODE,  LOGICAL_UNIT,  and  MODE  are  type  Byte  and  FILE_ 
NAME_  PTR  is  type  PByte  for  pointer  to  byte.  OPEN  is  an  external  routine  of  the 
PLZ.STREAM.IO  Module.  OPEN  calls  the  operating  system  to  open  a  disk  file. 


e.  WRITE(  LOGICALJJNIT,  TEXT_POINTER  ) 

where  LOGICALJJNIT  is  type  Byte  and  TEXT  JOINTER  is  type  PByte.  WRITE  is 
an  external  routine  of  the  Enhancements  Module.  WRITE  outputs  the  text  pointed 
to  by  TEXT  JOINTER  to  the  desired  LOGICALJJNIT. 


f.  WRITE_HBYTE(  LOGICALJJNIT,  VALUE  ) 

where  both  parameters  are  type  Byte.  WR1TEJHBYTE  is  an  external  routine  of 
the  Enhancements  Module.  WRITEJHBYTE  outputs  the  two  ASCII  characters 
that  represent  the  VALUE. 


g.  WRITE JHINTEGER(  LOGICALJJNIT,  VALUE  ) 

where  LOGICALJJNIT  is  type  Byte  and  VALUE  is  type  Integer.  WRITEJHINTE- 
GER  is  an  external  routine  of  the  Enhancements  Module  that  outputs  the  chara¬ 
cters  which  form  the  hexidecimal  representatio  of  VALUE  to  the  designated 
LOGICALJJNIT. 
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h.  WRITE_HWORD(  LOGICAL_UNIT,  VALUE  ) 

where  LOGICAL_UNIT  is  type  Byte  and  VALUE  is  type  Word.  WRITE_HWORD  is 
an  external  routine  of  the  Enhancements  Module.  WRITE_HWORD  outputs  the 
four  characters  which  form  the  hexidecimal  representation  of  VALUE  to  the  desig¬ 
nated  LOGICALJJNIT. 


i.  WRITELN(  LOGICALJJNIT,  TEXT_POlNTER  ) 

where  LOGICALJJNIT  is  type  Byte  and  TEXT_POINTER  is  type  PByte.  WRITELN 
is  an  external  routine  of  the  Enhancements  Module.  WRITELN,  like  WRITE 
above,  outputs  text;  WRITELN  adds  a  carriage  return  at  the  end  of  the  text  string. 


j.  OUT_ERROR_CODE  :=  ERRORJN_CREATE(  IN_ERROR_CODE, 

RETURN_CODE  ) 


where  all  three  parameters  are  type  Byte. 

Please  consult  the  descriptions  of  these  routines  for  more  information  on  their 
function. 


9.  Output  of  Routine 

If  something  goes  wrong  during  the  execution  of  CREATE_DATA_ 
FILE,  the  output  of  the  routine  is  ERROR_CODE  filled  with  FATAL.  If  all  goes  well, 
the  output  of  CREATE_DATA_FILE  is  an  open  disk  file  with  the  header  informa¬ 
tion  written  in.  The  output  parameter  ERROR_CODE  will  hold  FALSE  indicating 
successful  operation. 


10.  Routine  Flaws 

The  major  omission  in  CREATE_DATA_FILE  is  that  VALID_STRING 
isn’t  called  to  check  the  TESTID  or  the  CHANNEL  number.  Both  VALID_STRING 
and  ERROR_IN_CREATE  calls  should  follow  the  STRING_COPY  calls.  The 
second  problem  in  CREATE_DATA_F1LE  is  that  STRING_COPY  is  improperly 
called  COPY_ST!NG.  The  routine  also  badly  needs  commenting. 


LL  Reference  to  Listing 

CREATE_DATA_FILE’s  listing  is  on  page  384-385  in  Appendix  F. 
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1.  Routine  Name:  LOAD_DATA_FILE 

2.  Primary  subordinate  routine  of  Collect_Data  Module. 

3.  Written  in  PLZ;  16  lines  of  code. 

4.  Synopsis  of  Routine 

L0AD_DATA_F1LE  reads  the  data  loaded  into  memory  by  SAMPLER 
and  loads  that  data  into  the  disk  file  opened  by  CREATE_DATA_FILE.  Were  it 
not  for  error  checking,  LOAD__DATA_FILE  would  simply  be  a  call  to  PUTSEQ,  an 
external  routine  of  the  PLZ.STREAM.IO  Module,  to  write  the  data  to  memory.  Two 
error  checks  are  present  however.  First,  a  check  is  made  after  the  call  to 
PUTSEQ  checking  that  the  number  of  bytes  that  should  have  been  written  to  disk 
were  written  to  disk.  If  the  numbers  don't  match,  an  error  message  is  written  to 
the  system  console  via  the  external  output  routines  of  the  Enhancements  Module. 
The  output  parameter  ERROR_CODE  is  set  to  STORAGE_ERROR.  The  second 
error  check  is  on  the  operating  system  return  code  from  the  PUTSEQ  call.  If  the 
code  is  no  OPERATION_COMPLETE  an  error  message  is  again  written  to  the 
console.  In  this  case,  the  returned  ERROR_CODE  is  FATAL.  The  figure  below 
shows  the  relationship  between  LOAD_DATA_FILE  and  the  external  routines. 

5.  Routine  Relationship  Diagram 


Figure  72.  Relationship  of  LOAD_DATA_FILE  to  Other  Routines. 
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LOAD_DATA_FILE  is  invoked  from  SAMPLE_DATA  by 


ERROR_CODE  :=  LOAD_DATA_FILE( 


DATA_FILE, 
BUFFER_BEGINNING, 
LAST  DATA 


) 


where  ERROR_CODE  and  DATA_F1LE  are  type  Byte  and  BUFFERJ3EGINNING 
and  LAST_DATA  are  type  PByte  for  Pointer  to  Byte. 


7.  Variables  and  Constants 

LOAD_DATA_FILE  uses  three  internal  variables.  Their  types  and 
purposes  are  listed  below. 


Variable  Name 

TVD6 

Definition 

N  U  MBE  R_OF_BYTES 

Word 

The  number  of  bytes  of  data  in  the 
memory  buffer 

BYTES.WRITTEN 

Word 

Receives  the  return  parameter  from 
PUTSEQ  that  says  how  many  bytes 
were  actually  output. 

RETURN_CODE 

Byte 

Receives  the  return  parameter  from 
PUTSEQ  that  holds  the  operating 
system  return  code. 

LOAD_DATA_ 

_FILE  also  uses  a  few  constants.  They  are 

Constant  Name 

TvDe 

Definition 

STORAGE_ERROR 

23  hex 

Error  code  for  mismatch  in  number  of 
bytes  written  vs  number  of  bytes  in 
memory  buffer. 

CONSOLE_OUT 

02  hex 

Logical  unit  number  for  the  system 

console. 
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K 


OPERATION  COMPLETE 


FATAL 


80  hex 


FE  hex 


RIO  return  code  for  successful 
operation. 

Error  code  for  a  fatal  error  in 
Collect  Data. 


LOAD_DATA_FILE  calls  five  external  routines.  Their  invocations, 
parameters,  and  functions  are  listed  below. 


RETURN_CODE  :=  PUTSEQ( 


LOGICALJJNIT, 
BUFFER_PTR, 
NUMBER_OF_BYTES  ) 


where  RETURN_CODE  and  LOGICAL_UNIT  are  type  Byte,  BUFFER_PTR  is  type 
pointer  to  Byte,  and  NUMBER_OF_BYTES  is  type  Word.  This  external  routine  of 
the  PLZ.STREAM.IO  Module  is  used  by  LOAD_DATA_FILE  to  write  the  data 
stored  in  memory  into  the  disk  file. 


b.  WRITE(  LOGICAL_UNIT,  TEXT_POINTER  ) 

where  LOGICALJJNIT  is  type  Byte  and  TEXT_POINTER  is  type  PByte  for  pointer 
to  byte.  LOAD_DATA_FILE  uses  WRITE  to  output  error  messages  to  the  system 
console.  WRITE  is  part  of  the  Enhancements  Module. 


c.  WRITE_DWORD(  LOGICALJJNIT,  VALUE  ) 

where  LOGICALJJNIT  is  type  Byte  and  VALUE  is  type  Word.  This  external 
routine  of  the  Enhancements  Module  is  used  to  output  decimal  values  to  the 
system  console. 


d.  WRITELN(  LOGICALJJNIT,  TEXT_POINTER  ) 

where  LOGICALJJNIT  is  type  Byte  and  TEXT_POINTER  is  tv-e  PByte.  LOAD_ 
DATA_  FILE  uses  this  Enhancements  Module  routine  to  ou'oi-t  strings  of  chara¬ 
cters  to  the  system  console.  WRITELN,  unlike  WRITE,  outputs  a  carriage  return  at 
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the  end  of  the  character  string. 


e.  WRITELN_RCODE(  LOGICAL JJNIT,  RETURN_CODE  ) 

where  both  LOGICALJJNIT  and  RETURN_CODE  are  type  Byte.  LOAD_DATA_ 
FILE  uses  WRITELN_RCODE  to  translate  the  operating  system  return  code  into 
text  and  then  output  the  text  to  the  system  console.  WRITELN_RCODE  is  an  ex¬ 
ternal  routine,  an  element  of  the  PLZ.STREAM.IO  Module. 


If  all  goes  well  in  LOAD_DATA_FILE,  the  result  will  be  a  data  file  load¬ 
ed  with  the  data  from  the  memory  buffer  and  an  ERROR_CODE  of  FALSE.  If 
things  don't  go  well,  error  messages  will  be  written  to  the  console,  the  data  file 
will  be  in  an  indeterminant  state,  and  the  ERROR_CODE  will  be  FATAL  or 
STORAGE  ERROR. 


LOAD_DATA_FILE  is  flawed  in  that  ERROR_CODE  is  in  an  indeter¬ 
minant  state  if  every  thing  goes  well.  To  fix  this  flaw,  an  additional  statement 
initializing  ERROR_  CODE  to  FALSE  (error  code  for  no  error)  should  be  added  to 
LOAD_DATA_FILE.  This  statement  should  be  inserted  prior  to  the  PUTSEQ  call. 
Also,  LOAD_DATA_FILE  is  devoid  of  commenting. 


F. 


The  program  listing  of  LOAD_DATA_FILE  is  on  page  386  in  Appendix 
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1 .  Routine  Name:  CLOSE_DATA_FILE 

2.  Primary  subordinate  routine  of  Collect_Data  Module 

3.  Written  in  PLZ;  7  lines  of  code. 


4.  Synopsis  of  Routine 

This  short  routine  closes  the  data  file  opened  by  CREATE_DATA_ 
FILE  and  filled  by  LOAD_DATA_FILE;  it  is  the  last  routine  called  by  SAMPLE_ 
DATA,  the  executive  routine  of  Collect_Data  Module.  CLOSE_DATA_FILE 
closes  the  file  with  a  call  to  the  external  routine  CLOSE.  If  the  operation  was 
successful,  CLOSE_DATA_FILE  ends.  Otherwise,  CLOSE_DATA_FILE  outputs 
an  error  message  to  the  sytem  console  and  returns  the  FATAL  error  code.  The 
relationship  of  CL0SE_DATA_F1LE  to  its  calling  routine  and  its  subordinate 
routines  is  shown  in  the  figure  below. 


5.  Routine  Relationship  Diagram 


Figure  73.  Relationship  of  CLOSE_DATA_FILE  to  Other  Routines 
6,  Invocation 
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CLOSE_DATA_FILE  is  invoked  from  SAMPLE_DATA  via 

ERROR_CODE  :=  CLOSE_DATA_FILE(  DATA_FILE  ) 

where  both  ERROR_CODE  and  DATA_FILE  are  type  Byte.  ERROR_CODE  re¬ 
turns  to  SAMPLE_DATA  a  code  indicating  success  or  failure.  DATA_FILE  is  the 
logical  unit  number  of  the  data  file. 


7.  Variables  and  Constants 

CLOSE_DATA_FILE  uses  one  internal  variable,  RETURN_CODE 
(type  Byte).  This  variable  receives  the  return  parameter  from  the  call  of  CLOSE. 

Two  constants  are  used  by  CLOSE_DATA_FILE,  OPE  RATION  JSOM- 
PLETE  (value  80  hex)  and  FATAL  (value  FE  hex).  OPERATION_COMPLETE  is 
the  RIO  Operating  System  return  code  for  successful  completion.  FATAL  is  the 
Collect_Data  Module  error  code  for  failed  operations. 


8.  Other  Routines  Called 

LOAD_DATA_FILE  calls  four  external  routines.  Their  names,  para¬ 
meters,  and  functions  are  listed  below. 

RETURN_CODE  :=  CLOSE(  LOGICAL_UNIT ) 

where  both  parameters  are  type  Byte.  RETURN_CODE  is  the  operating  system’s 
message  on  success  or  failure  of  the  file  closing  procedure.  LOGICALJJNIT  is 
the  number  of  the  unit  to  be  closed.  CLOSE  is  a  routine  of  the  PLZ.STREAM.IO 
Module. 


WRITE(  LOGICALJJNIT,  TEXT_STRING ) 

where  LOGICALJJNIT  (type  Byte)  is  the  device  number  to  which  output  is 
directed  and  TEXT_STRING  (type  PByte)  is  a  pointer  to  the  string  of  text  to  be 
output.  CLOSE_DATA_  FILE  uses  WRITE  to  output  an  error  message  to  the 
system  console.  WRITE  is  a  member  of  the  Enhancements  Module. 

WRITELN_RCODE(  LOGICALJJNIT,  RETURN_CODE ) 

where  both  parameters  are  of  type  Byte.  LOGICALJJNIT  is  the  device  number  to 
which  output  is  directed.  RETURN_CODE  is  the  operating  system  code  that 
WRITELN_RCODE  will  translate  into  its  text  definition  and  output  the  text  to  the 
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designated  L0G1CALJJNIT.  CLOSE_DATA_FILE  uses  this  external  routine  from 
the  Enhancements  Module  to  output  the  translated  return  code  to  the  console  in 
the  error  message. 

WRITELN(  LOGICAL JJNIT,  TEXT_POINTER  ) 

where  LOGICAL JJN1T  is  type  Byte  and  TEXT_POINTER  is  type  PByte.  LOGI- 
CAL_UNIT  is  the  device  number  for  the  output.  TEXT_POINTER  points  to  the 
string  of  characters  to  be  output.  WRITELN,  like  WRITE,  is  used  by  CLOSE_ 
DATA_FILE  to  send  error  messages  to  the  system  console.  Unlike  WRITE, 
WRITELN  concludes  the  text  string  with  a  carriage  return.  WRITELN  is  an 
external  routine  from  Enhancements  Module. 


9.  Output  of  Routine 

CLOSE_DATA_FILE  closes  the  disk  file  into  which  the  data  collected 
from  the  AIO  board  was  stored. 


10.  Routine  Flaws 

Like  several  other  routines  of  CollectJOata  Module,  ERROR_CODE  is 
not  initialized.  An  additional  line  of  code  to  initialize  ERROR_CODE  to  FALSE  is 
needed.  Also  like  the  later  routines  of  Collect_Data  Module,  CLOSE_DATA_ 
FILE  needs  commenting. 


11.  Reference  to  Listing 

CLOSE_DATA_FILE's  code  listing  is  on  page  387  in  Appendix  F. 
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1.  Routine  Name:  ERROR_IN_SAMPLER 

2.  Subordinate  routine  of  Col!ect_Data  Module 

3.  Written  in  PLZ;  8  lines  of  code. 


ERROR_IN_SAMPLER  is  a  error  detection  /  error  message  writing 
routine  that  SAMPLE_DATA  calls  after  the  call  to  the  external  routine  SAMPLER. 
SAMPLER  returns  an  error  code  to  SAMPLE_DATA.  If  the  error  code  is  other 
than  FALSE,  SAMPLE_DATA  calls  ERROR_IN_SAMPLER  to  send  the  proper 
error  messages  to  the  system  console.  ERROR_IN_SAMPLER  also  calls 
CLOSE  DATA  FILE  and  returns  to  SAMPLE  DATA  a  FATAL  error  code. 


SAMPLE  DATA 


ERROR  IN  SAMPLER 


a 


CLOSE  DATA  FILE 


WRITELN 
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OUT_ERROR_CODE  :=  ERRORJN_SAMPLER(  IN_ERROR_CODE  ) 
where  both  parameters  are  of  type  Byte. 


No  variables  other  than  the  input  and  output  parameters  are  used  by 
ERROR_IN_SAMPLER.  Four  constants  are  used.  ABORT  (value  AB  hex)  is  the 
error  code  from  SAMPLER  that  data  collection  was  terminated.  CONSOLE_OUT 
(value  02  hex)  is  the  logical  unit  number  of  the  system  console.  DATA_FILE 
(value  07  hex)  is  the  logical  unit  number  of  the  disk  file  opened  by  CREATE_ 
DATA_FILE.  Last  is  FATAL  (value  FE  hex),  the  error  code  for  a  fatal  error. 


ERROR_IN_SAMPLER  calls  two  routines,  WRITELN  and  CLOSE_ 
DATA_FILE.  Their  invocations,  parameters,  and  functions  follow. 

WRITELN(  LOGICALJJN1T,  TEXT_POINTER ) 

where  LOGICALJJNJT  (type  Byte)  indicates  the  logical  unit  and  TEXT_PO INTER 
(type  PByte  for  Pointer  to  Byte)  points  to  the  string  to  be  output.  This  external  rou¬ 
tine  of  the  Enhancements  Module  also  outputs  a  carriage  return  at  the  end  of  the 
text  string.  ERROR_IN_SAMPLER  uses  WRITELN  to  output  error  messages  to 
the  system  console. 

ERRORjCODE  :=  CLOSE_DATA_FILE(  FILE_UNIT ) 

where  ERROR_CODE  (type  Byte)  indicates  whether  the  closing  was  successful 
and  FILE_UNIT  (type  Byte)  is  the  logical  unit  number  of  the  file  to  be  closed. 


ERROR_IN_SAMPLER  is  called  only  if  SAMPLE_DATA  finds  a  non- 
FALSE  error  code  returning  from  SAMPLER.  Thus  something  has  already  gone 
wrong.  ERROR_IN_SAMPLER's  output  is  messages  to  the  system  console  and 
the  closing  of  the  data  file  opened  by  CREATE_DATA_FILE.  ERROR_IN_SAM- 
PLER  always  returns  a  FATAL  error  code. 
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The  only  flaw  is  that  SAMPLE_DATA  calls  ERROR_IN_S AMPLER 
only  when  it  detects  an  error.  A  superior  organization  would  be  to  have  SAM- 
PLE_DATA  call  ERROR_IN_SAMPLER  immediately  after  SAMPLER  without 
checking  the  error  code.  ERROR_IN_SAMPLER  would  determine  if  any  error 
had  occured  and  return  an  error  code  of  FALSE  for  all  nonfatal  errors.  The  IF 
statements  inside  a  DO  loop  structure  used  by  PREPARE_COLLECTOR  would 
be  one  approach  with  IF  statements  for  each  expected  error  code  and  a  "wild 
error"  message  for  the  unexpected. 


1 1 .  Reference  to  Listing 

The  program  listing  of  ERROR_IN_SAMPLER  is  on  page  388  in 
Appendix  F. 


I 


; 


< 
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1.  Routine  Name:  SAMPLE  DATA 


2.  Executive  routine  of  Collect_Data  Module. 


3.  Written  in  PLZ;  17  lines  of  code. 


SAMPLE_DATA  is  the  executive  routine  of  the  Collect_Data  Module. 
All  the  other  routines  of  Collect_Data  Module  are  called  either  directly  or  indirect¬ 
ly  by  SAMPLE_DATA.  The  figure  below  shows  the  basic  execution  flow  of  SAM- 
PLE_DATA  and  the  principal  subordinate  routines  it  calls.  Included  in  this  list  is 
SAMPLER,  the  executive  routine  of  Sampler  Module,  the  assembly  language 
module  that  performs  the  actual  data  collection. 

The  execution  revolves  around  five  major  processes.  First  User  sup¬ 
plied  instructions  are  translated  by  PREPARE_COLLECTOR  into  the  command 
necessary  to  program  the  CTC  driven  interrupt  timer.  Next,  again  with  user  in¬ 
puts,  a  disk  file  is  opened  in  process  CREATE_DATA_FILE.  Third,  the  analog 
data  is  read  in  and  stored  in  memory.  This  process  is  the  responsibility  of  the 
Sampler  Module.  The  data  stored  in  memory  is  then  written  into  the  disk  file  by 
LOAD_DATA_FILE.  Lastly,  the  now  filled  data  file  is  closed  by  CLOSE_DATA_ 
FILE.  Thoughout  this  process,  if  anything  goes  wrong  an  error  message  is  output 
to  the  system  console. 

SAMPLE_DATA,  and  hence  all  of  Colllect_Data  Module,  is  designed 
to  be  called  from  a  superior  PLZ  routine.  The  responsibility  of  that  superior  rou¬ 
tine  is  the  interface  with  the  user. 
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Figure  75.  Relationship  of  SAMPLE_DATA  to  its  Calling  Routine  and  to 

its  Subordinate  Routines. 
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SAMPLE_DATA  is  invoked  from  its  calling  routine  with 


ERROR.CODE  :=  SAMPLE_DATA(  TESTID,  USER_MESSAGE, 

PERIOD_VALUE,  PERIOD_UNITS, 
INPUT_CHANNEL,  SAMPLES  ) 


The  type  and  purpose  of  these  parameters  is  listed  below. 


Parameter  Name  Tvoe  _ Definition _ 

ERROR_CODE  Byte  Return  parameter  to  indicate  to  the 

calling  routine  whether  execution  was 
successful. 

TESTID  ASCII_STRING  A  string  holding  the  six  character 

sequence  that  uniquely  identifies  the 
test. 


USER_MESSAGE 

PERIOD_VALUE 

PERIODJJNITS 

INPUT_CHANNEL 

SAMPLES 


ASCII_STRING  A  string  holding  a  free  field  message. 

Integer  The  number  of  time  units  desired  for 

the  sampling  period. 

Integer  The  units  of  PERIOD_VALUE.  Defined 

units  are  MICROSECONDS,  MILLI¬ 
SECONDS,  and  SECONDS. 

Byte  The  number  of  the  desired  analog 

input  channel  on  the  AIO  board. 

Word  The  number  of  data  samples  the  user 

wants  collected. 


7,  Variables  and  Constants 

SAMPLE_DATA  uses  three  variables  in  addition  to  the  parameters 
addressed  above.  They  are 

Variable  Name  Type  _ Definition _ 

TODAYS_DATA_BUF  ASCII_STRING  A  buffer  to  hold  the  characters  that 

renresent  the  date  tvvmmdd^ 


TODAYS  DATE  ASCII  PT 


A  pointer  to  TODAYS_DATE_BUF. 


LAST_DATA  PByte  A  pointer  to  the  memory  location  that 

holds  the  last  byte  of  the  data 
collected. 


SAMPLE_DATA  also  makes  use  of  a  number  of  constants.  They  are 


Constant  Name 

TvDe 

Definition 

FALSE 

00  hex 

The  error  code  for  nothing  went  wrong. 

FATAL 

FE  hex 

The  error  code  a  fatal  error. 

DATA_FILE 

07  hex 

The  logical  unit  number  for  the  data 

file. 


8.  Other  Routines  Called 

SAMPLE_DATA  calls  seven  subordinate  routines  and  uses  one 
buffer.  Six  of  these  are  members  of  the  Collect_Data  Module.  They  are 

GET_DATE, 

PREPARE_COLLECTOR, 

CREATE_DATA_FILE, 

ERROR_IN_SAMPLER, 

LOAD_DATA_FILE,  and 
CLOSE_DATA_FILE. 

The  invocation,  parameters,  and  functions  of  these  routines  will  not  be  discussed 
here.  These  items  are  detailed  in  the  descriptions  of  these  routines.  One  impor¬ 
tant  note  however.  Several  of  the  above  routines  call  input/output  routines  of  the 
PLZ.STREAM.IO  Module.  The  PLZ.STREAM.IO  Module  must  be  linked  in  with 
Collect_Data  Module.  The  routines  called,  OPEN,  CLOSE,  and  PUTSEQ,  must 
be  declaired  external  routines. 

The  other  subordinate  routine  called  by  SAMPLE_DATA  is  SAM¬ 
PLER,  an  external  routine  of  the  Sampler  Module.  SAMPLER  sets  up  the  CTC 
interrupts,  programs  the  AIO  analog  to  digital  input,  polls  the  user  for  a  "GO"  sig¬ 
nal,  and  then  reads  in  data  from  the  AIO  board  and  stores  it  in  memory.  SAM¬ 
PLER  is  invoked  from  SAMPLE  DATA  with 
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ERROR.CODE,  LAST_DATA  := 

SAMPLER(  IO_CHANNEL,  CTC_MODE, 
TIME_CNST,  COUNT, 
SAMPLES,  FIRST_DATA  ) 

The  type  and  purpose  of  these  input  and  output  parameters  follows. 


ERROR_CODE  Byte  Returns  a  code  which  indicates  whe¬ 

ther  data  collection  was  successful  or 
tells  what  went  wrong.  Five  codes 
are  defined.  FALSE:  no  error;  ABORT: 
user  abort;  FATAL:  complete  break¬ 
down;  CHANNELJNVALID:  channel 
number  was  out  of  range;  MODE_ 
INVALID  CTC  commands  were  invalid. 


LAST_DATA 

PByte 

Returns  a  pointer  to  the  memory  loca¬ 
tion  in  which  the  last  byte  of  data  was 
stored. 

IO_CHANNEL 

Byte 

Passes  in  the  number  of  the  AIO 
Channel  to  be  used  for  data  collection. 
(0  to  15) 

CTC_MODE 

Byte 

The  first  of  two  programming  bytes  for 
the  CTC  passed  into  SAMPLER. 

CTC  MODE  has  two  possible  values, 
FAST_MODE  (87  hex)  and  SLOW_ 
MODE  (A7  hex).  Both  set  the  CTC  to 
generate  periodic  interrupts. 

TIME_CNST 

Byte 

The  second  CTC  timing  value  passed 
in.  Its  defined  range  is  0  to  255 
decimal.  This  byte  tells  the  CTC  the 
value  of  the  internal  counter. 

COUNT 

Word 

The  number  of  CTC  generated  inter- 
rutps  per  AIO  analog  to  digital 
conversion. 

NUM_SAMPLES 

Word 

The  number  of  twelve  bit  samples 
(stored  in  two  eight  bit  locations)  to  be 
collected. 
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FIRST  DATA 


PByte 


A  pointer  to  the  memory  location 
where  the  first  byte  of  data  collected  is 
to  be  stored. 


In  order  for  SAMPLER  to  be  called  by  SAMPLE_DATA,  it  must  be  declaired  exter¬ 
nal  and  Sampler  Module  must  be  linked  in  with  Collect_Data  Module. 

The  third  external  structure  used  by  SAMPLE_DATA  is  DATA_BUF- 
FER,  a  2,000  byte  memory  allocation  set  up  by  Buffers  Module.  This  buffer  is 
used  inconjunction  with  routine  SIZE_DATA_BUFFER  (an  internal  routine  sub¬ 
ordinate  to  PREPARE_COLLECTOR)  to  define  the  storage  space  used  by  SAM¬ 
PLER  to  store  the  data  read  in  from  the  AIO  board.  This  simple  approach  is  only 
indended  for  initial  checkout  of  Collect  Data  Module.  Ultimately,  SIZE_DATA_ 
BUFFER  would  work  directly  with  the  RIO  operating  system  memory  manager. 
Then,  the  data  buffer  would  be  dynamically  allocated  rather  than  limited  to  some 
arbitrary  preselected  size.  Access  to  the  memory  manager  from  SIZE_DATA_ 
BUFFER  would  be  provide  by  ALLOCATE  and  DEALLOCATE,  external  routines 
of  the  Utility  Module. 


9,  Output  of  Routine 

There  are  two  classes  of  SAMPLE_DATA  (and  hence  Collect_Data) 
outputs.  First,  if  all  goes  sufficiently  well  in  both  Collect_Data  Module  and  Sam¬ 
pler  Module,  the  output  will  be  a  new  file  on  the  system.  That  file  will  contain 
header  information  on  the  data  collected  and  up  to  2,000  bytes  of  data  read  in 
from  the  AIO  analog  to  digital  converter.  The  second  class  of  outputs  covers  the 
outcome  when  fatal  errors  or  user  aborts  occur.  For  most  errors,  execution  of 
SAMPLE_DATA  will  end.  For  a  couple  of  cases,  a  data  file  will  have  been 
created  and  filled  with  header  information  but  no  data  will  be  present. 


iQ,  Routine .Fte, 

There  is  one  structural  flaw  in  SAMPLE_DATA  ,  a  number  of  listing 
errors,  and  a  lack  of  comments.  The  sturctural  flaw  is  that  if  a  fatal  error  occurs 
during  LOAD_  DATA_FILE,  the  current  logic  flow  has  SAMPLE_DATA  just  end, 
leaving  the  data  file  open.  Reguardless  of  the  error,  the  data  file  should  be 
closed  by  calling  CLOSE_  DATA_FILE.  The  conditional  exit  following  the  call  to 
LOAD  DATA  FILE  should  be  eliminated. 
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The  listing  of  SAMPLE_DATA  has  three  mislabled  parameters  in  calls 
to  subordinate  routines.  First,  in  the  call  to  CREATE_DATA_FILE  ,  the  third  input 
parameter  should  be  the  constant  DATA_FILE  rather  than  FILEJJNIT.  Then  in 
the  calls  to  SAMPLER  and  LOAD_DATA_FILE,  the  parameter  currently  listed  as 
BEGINNING_OF_  BUFFER  should  either  be  changed  to  ADATA_BUFFER[0]  (a 
pointer  to  the  first  location  of  the  data  buffer)  or  be  defined  as  local  variable  of 
type  PByte  and  set  equal  to  ADATA_  BUFFER[0]  early  in  SAMPLE_DATA. 

The  final  flaw  in  SAMPLE_DATA  is  its  lack  of  comments.  The  use  of 
an  alternate  format  for  the  rather  lengthy  subordinate  routine  calls  would  also  aid 
readability  of  the  routine. 


1.1.  Reference  to  Listing 

The  listing  of  SAMPLE_DATA  is  on  page  389  in  Appendix  F. 
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VII.  Conclusion 


The  system  designed  around  the  hardware  of  the  Zilog  MCZ  Z-80 
Development  System  is  a  reasonable,  general  purpose  data  collection  system. 
The  design  supports  the  requirements  for  acuracy,  data  integrity,  flexibility,  and  a 
simple  user  interface  presented  in  Section  1.  The  design  is  based  on  having  an 
data  storage  unit  located  with  in  the  item  under  test.  This  internal  unit  would  store 
the  data  until  post  test  when  the  data  would  be  transfered  out  to  an  external 
control  and  data  storage  unit. 

The  purpose  of  the  thesis  effort  was  to  examine  and  develop  the 
software  required  to  implement  such  a  data  collection  system.  The  first  step  was 
to  provide  some  improvements  to  the  PL Z  language.  The  software  written  to 
improve  the  Pascal-like  PLZ  language  proved  quite  useful  and  effective.  These 
10  routines,  written  in  PLZ,  of  the  Enhancements  Module  were  fully  developed 
and  tested.  Hardware  and  operating  system  access  routines  were  also  written 
to  supplement  PLZ.  These  assembly  language  routines  of  the  Utility  Module 
were  also  fully  developed  and  checked  out. 

Like  the  PLZ  improvement  software,  the  software  written  for  the  data 
collection  system  was  written  in  both  PLZ  and  Z-80  assembly  language.  Since  a 
single  development  system  was  used  for  both  the  internal  data  collection  /  temp¬ 
orary  storage  unit  and  the  external  control  /  archive  unit,  the  division  of  software 
between  the  units  became  some  what  blurred.  The  software  of  the  Collect_Data 
Module,  and  its  subordinate  Sampler  Module,  implement  one  of  the  five  pro¬ 
cesses  of  the  data  collection  system,  the  collection  and  storage  of  data.  The 
Sampler  Module  software  is  that  of  the  internal  data  collection  /  temporary 
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storage  unit;  the  Collect_Data  software  would  be  resident  in  the  external  control  / 
data  archive  unit.  This  software  was  never  fully  functional.  The  problem  appears 
to  be  in  the  interface  between  PLZ  language  calling  routines  and  the  Z-80 
assembly  language  Sampler  Module.  Though  the  software  was  not  functional,  it 
did  fulfull  the  purpose  of  examining  the  software  required  to  implement  a  data 
collection  system. 

Recommendations 

Two  courses  of  future  action  are  clearly  open.  The  software  of  the 
data  collection  system  could  be  completed  and  thoroughly  tested.  This  would 
include  integration  of  the  Set  Up  Scale  Factor  File  software  and  implementation 
of  the  three  processes  (Scale  Data,  Output  Data,  and  User  Data  Manipulations) 
not  implemented  during  this  effort.  The  second  course  of  action  would  be  to  build 
one  of  the  internal  data  collection  units.  This  activity  should  not  be  started  until 
the  software  portion  of  the  system  is  complete. 
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Appendix  A: 

Enhancements  Module  Listings 


The  following  36  pages  are  the  compiler  listing  of  the  Enhancements 
Module,  the  DEBUGS  Module,  and  TESTJT  Module.  DEBUGS  Module  is  a 
special  subset  of  Enhancements  Module  used  for  debugging  of  PL Z  programs 
which  interact  with  the  RIO  Operating  System.  TESTJT  Module  is  one  set  of 
routines  used  to  test  the  routines  of  Enhancements  Module.  The  following  is  a  list 
of  the  routines  found  on  each  page. 

Page  Number  _ Contents 


279  Constant,  Type,  and  External  Declarations  of  Enhancements 
Module. 

280  Procedure  ASCII 

281  Procedure  VALUE 

282  Procedure  VALUE_LOOP 

283  Procedures  PUTCH  and  GETCH 

284  Procedure  GET_ASCII_CH 

285  Procedure  PLACE_LOOP 

286  Procedures  VALID_BINARY_CH  and  VALID_DECIMAL_CH 

287  Procedure  VALID_HEX_CH 


288  WRITE  and  WRITELN  Procedures 

289  WRITE_DBYTE  and  WRITELN_DBYTE  Procedures 

290  WRITEJHBYTE  and  WRITELN_HBYTE  Procedures 

291  WRITE_BBYTE  and  WRITE LN_BBYTE  Procedures 

292  WRITE  J.BYTE  and  WRITELN  J.BYTE  Procedures 

293  WRITE JDINTEGER  and  WRITELN  J) INTEGER  Procedures 

294  WRITE_DWORD  and  WRITELN_DWORD  Procedures 

295  WRITE  HWORD  and  WRITELN  HWORD  Procedures 
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296 

WRITE_POINTER  and  WRITELN_POINTER  Procedures 

297-298 

WRITE_RCODE  and  WRITELN_RCODE  Procedures 

299 

Procedure  READLN 

300 

Procedure  READJHBYTE 

301 

Procedure  READ_DBYTE 

302 

Procedure  READ_BBYTE 

303 

Procedure  READ_LBYTE 

304-305 

Procedure  READ_DINTEGER 

306 

Procedure  READ_HWORD 

307 

Procedure  READ  DWORD 

308-309  DEBUGS  Module 

310-314  TESTJT  Module 
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137  9  INDEX  :=  INDEX  +  1 

138  10  FiOCR  :=  F/OCR  *  MULTI  ELER 

139  CD 

140  11  END  VALUEIiXP 
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Appendix  B:  Utility  Module  Listings 


The  following  1 7  pages  are  the  assembler  listing  of  the  Utility  Module 
routines  and  listing  of  two  modules  of  testing  routines.  The  contents  of  these 
pages  is 


316  Introduction  Comments 

31 7  IOOUT  Routine  Comments  and  Listing 

318  IOIN  Routine  Comments  and  Listing 

319  MENSET  Routine  Comments  and  Listing 

320  MEMREAD  Routine  Comments  and  Listing 

321  DISABLEINT  Routine  Comments  and  Listing 

322  ENABLEINT  Routine  Comments  and  Listing 

323  DATE  Routine  Comments  and  Listing 

324-325  ALLOCATE  Routine  Comments  and  Listing 

326-327  DEALLOCATE  Routine  Comments  and  Listing 

328  Equates  for  Utility  Module 

329  Symbol  Cross  Reference  Table  for  Utility  Module 


330  TESTS  Module 

331-332  ASMTEST  Module 
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Appendix  C: 

Time  Compairson  Using  PLZ 


As  discussed  in  the  introduction  to  Sampler  Module,  assembly  language  was 
selected  primarly  for  a  speed  advantage.  In  Sampler  Module  (routine  COLLECTER) 
only  four  assembly  language  instructions  are  needed  to  read  a  value  in  from  an  10  port 
and  check  the  value  against  a  constant.  The  alternative  was  to  use  a  PLZ  routine  which 
calls  the  Utility  Module  routine  IOIN.  The  listing  below  is  an  estimate  of  the  assembly 
language  coding  required  to  accomplish  the  read  and  compair  with  PLZ  and  the  Utility 
Module  IOIN. 


_Lab!e_ 


Cyclas 


imment 


LOOP: 

on 

(input 

LD 

PUSH 

LD 

PUSH 

JP 

HL,RETURN_ADDRESS  4 

HL  3 

HL,  IX+OFFSET  5 

HL  3 

IOIN  3 

Save  the  return  address 

the  system  stack 

Put  the  IO  port  number 

parameter)  on  the  stack 
Go  to  IOIN 

...............  u  u  my  iviuuuic?  —————— 

IOIN: 

PUSH 

IX 

4 

Save  Calling  Routine's  IX 

LD 

IX, ZERO 

4 

Clear  IX  register 

ADD 

IX, SP 

4 

Get  Offset  for  Parameters 

LD 

C,(IX+4) 

5 

Get  10  Port  Number 

IN 

A.(C) 

3 

Call  10  Port 

LD 

(IX+6),A 

5 

Load  Return  Parameter 

LD 

(IX+7),  ZERO 

5 

Fill  upper  byte  of  return 

parameter. 

POP 

IX 

4 

Get  calling  routine's  IX 

POP 

HL 

3 

Get  Return  Address 

FOP 

DE 

3 

Clear  Parameter  Space 

JP 

(HL) 

1 

Return  to  Calling  Routine 

Appendix  C 
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IX 

4 

IY.ZERO 

4 

Set  offsets  for  return 

IV, SP 

4 

parameters 

r,(IY+dn) 

5 

Save  return  parameter  in 

(IX+d-j),r 

5 

Local  AREC. 

rx,(IX+di) 

5 

Get  the  returned  value 

ry,(IX+d) 

5 

Get  the  check  value 

rx,ry 

5 

Com  pair  the  values 

LINE1 

2 

They  don't  match 

(IX+d3),TRUE 

5 

They  match,  logical  TRUE 

LINE2 

3 

Continue 

(IX+d3), FALSE 

5 

They  dont'match,  FALSE 

rx,(IX+d3) 

5 

Get  result  of  compairson 

ry,(IX+d4) 

5 

Get  compairson  value 

rX’ry 

2 

Check  the  values. 

BRANCH 

2 

Data  is  in,  go  to  next 
section  of  code. 

LOOP 

3 

Data  is  not  ready,  cyle 
through  again. 

Sum  of  Cycles 


129: 

130: 


Data  is  Ready 
Data  is  Not  Ready 


With  a  clock  period  of  1 .56  psec  per  cycle  (Ref  2),  the  estimated  times 
for  execution  are  201  psec  when  data  is  ready  and  203  psec  when  data  is  not 
ready.  In  compairson,  the  four  lines  of  assembly  language  used  in  routine 
COLLECTER  require  only  16  psec.  This  substantial  difference  in  time  is  due  to 
the  overhead  of  parameter  passing  between  routines  and  the  overhead  of  PLZ's 
activation  records  (AREC)  used  to  keep  track  of  parameters.  (Ref  6  and  9) 
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Appendix  D:  Sampler  Module  Listings 


The  following  21  pages  are  the  assembler  listing  of  the  Sampler  Mod¬ 
ule.  In  addition,  there  is  the  9  page  listing  of  TEST3,  a  routine  used  in  the  initial 
work  with  the  AIO  board.  Some  of  the  code  in  TEST3  is  repeated  in  Sampler 
Mod-  ule.  The  contents  of  these  pages  is 

Page  Number  _ Contents 


336 

Blank 

337 

Introduction  Comments 

338 

SAMPLER  Routine 

339 

VALIDATE  Routine 

340 

ATODINIT  Routine 

341 

CTC_PROGRAM  Routine 

342-343 

INT_SET_UP  Routine 

344 

INIT_COLLECTER 

345-346 

USER_READY?  Routine 

347 

START_TIMER  Routine 

348 

COLLECTER  Routine 

349 

CTC_OFF  Routine 

350 

TO_S AMPLE  and  TC_SAMPLE  Routines 

351 

DEALLOCATE  Routine 

352 

Definition  of  Storage  Locations  for  Sampler  Module 

353-354 

Equates  for  Utility  Module 

355-356 

Symbol  Cross  Reference  Table  for  Utility  Module 

357-366 

TEST3  Module 
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Appendix  G:  AIO.PLZ.S  Module  Listings 


Introduction  to  AIO.PLZ.S  Module 


To  determine  how  to  use  the  AIO  Analog  Input  Output  board  of  the 
MCB  Z-80  development  system,  the  PLZ  language  routines  of  the  AIO.PLZ.S 
Module  were  written.  These  routines  permitted  the  initial  operation  and  checkout 
of  the  board  and  served  as  software  "breadboards"  for  the  assembly  language 
routines  of  Sampler  Module  actually  employed  in  the  final  software. 


The  five  PLZ  language  routines  of  AIO.PLZ.S  Module  and  their 
functions  are: 


AIOJNIT: 

IN_CHAN_SEL: 

IN_DIGITALP: 

I 

N_DIGITALT: 
OUT  ANALOG: 


Initializes  the  AIO  board; 

Selects  one  of  the  sixteen  analog-to-digital  input 
channels  and  initiates  the  conversion; 

Reads  in  data  from  the  selected  input  channel; 

Selects  an  input  channel,  initiates  analog-to-digital 
conversion,  and  reads  data  in  from  the  channel;  and 

Outputs  data  on  a  selected  digital-to-analog  channel. 


To  accomplish  these  functions,  these  five  PLZ  routines  use  four  exter¬ 
nal  assembly  language  procedures  from  the  Utilities  Module.  The  routines  and 
their  functions  are: 


IOOUT: 

IOIN: 

ENABLEINT: 

DISABLEINT: 


Writes  a  byte  to  an  input/output  port, 
Reads  a  byte  from  an  input/output  port, 
Enables  the  CPU  interrupts,  and 
Disables  the  CPU  interrupts. 


The  relationship  between  the  AIO.PLZ.S  Module  routines,  calling  routines,  and 
the  Utility  Modue  routines  is  shown  in  Figure  76  below. 


Three  of  the  AIO.PLZ.S  routines,  AIOJNIT,  IN_CHAN_SEL,  and  IN_ 
DIGITALP,  were  initially  used  in  in  this  thesis  effort.  They  were  replaced  with  as¬ 
sembly  language  versions  of  these  routines  to  yield  greater  speed  of  execution. 
The  AIO.PLZ.S  Module  routines  obtain  access  to  the  AIO  board  through  two  other 
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^  modules,  UTILITY  and  PL Z  STREAM.IO.  The  assembly  language  routines 

directly  communicate  with  the  AIO  board.  The  PLZ  routines  however,  were  quite 
helpful  during  initial  development  of  the  higher  level  modules  of  the  thesis  effort. 


The  following  pages  detail  the  five  PL 2  language  routines  of  the  AIO. 
PLZ.S  Module.  For  each  routine  the  following  information  will  be  presented. 

1.  The  name  of  the.  routine. 

2.  The  name  of  the  routine's  module. 

3.  The  language  of  the  routine  and  the  number  of  lines  of  code. 

4.  A  synopsis  of  the  routine. 

5.  A  diagram  showing  the  relationship  of  the  routine  with  other 

routines,  both  calling  and  called. 

6.  How  the  routine  is  invoked  including  parameter  passing  schema 

and  a  list  of  the  calling  routines. 

7.  A  list  and  description  of  the  global,  module,  and  routine  level 

variables  and  constants. 

8.  A  fist  of  the  other  routines  called  including  a  description  of  their 

function  and  their  parameter  passing  schema. 

9.  Descriptions  of  the  output  parameters  of  the  routine  and  any 

system  configuration  changes  it  makes. 

10.  A  discussion  of  the  test  performed  on  the  routine  and  the  results  of 

those  tests. 

11.  A  reference  to  the  program  listing  of  the  routine. 
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1.  Routine  Name:  AIO  INIT 


2.  Part  of  AIO. PLZ.S  Module 


3.  Written  in  PLZ;  nine  lines  of  executable  code. 


AIOJNIT  initializes  the  AIO  Analog  Input  Output  board  of  the  Z-80  develop¬ 
ment  system.  To  prevent  inadvertent  interrupts  during  this  initialization  process, 
the  first  action  of  AIOJNIT  is  to  call  the  external  routine  DISABLEINIT.  The  AIO 
initialization  is  accom-  plished  by  writing  commands  to  the  control  ports  of  the 
board.  The  external  routine  IOOUT  is  used  for  this  writing.  The  AIO  board  is  put 
into  polled  mode  and  inhibited  from  issueing  interupts..  The  input  registers  of  the 
AIO  board  are  then  cleared  by  reading  them  via  the  external  routine  JOIN.  Lastly, 
the  system  interrupts  are  enabled  by  calling  the  external  routine  ENABLEINT. 


i-lPUMlKilll 


Calling  PLZ  Routines 


AIO  INIT 


>  Utility 
'Module 


IOOUT 


JOIN  DISABLEINT  ENABLEINT 


AIO  Board 


Z-80  CPU 


Figure  77.  Relationship  of  AIOJNIT  to  Calling  PLZ  Routine  and  the 

External  Routines. 
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a.  Invocation  Statement 


AIOJNIT  is  invoked  solely  by  its  name.  To  be  invoked  however,  both 
the  AIO.PLZ.S  and  UTILITY  modules  must  be  linked  in  with  the  calling  routine's 
module. 


b.  Parameter  Passing  Schema 

There  are  no  input  parameters  for  AIOJNIT. 


c.  Routines  Which  Call 

AIOJNIT  can  be  called  by  any  PLZ  routine  using  the  AIO  board.  For  this 
thesis  effort,  AIOJNIT  was  used  during  initial  work  with  the  AIO  board.  For  the 
combined  modules  of  the  thesis  effort,  and  assembly  language  program,  AIOINIT, 
similar  in  function  to  AIOJNIT,  was  used. 


7.  Variables,  and  Constants 

a.  Global 

AIOJNIT  uses  no  globally  defined  variables  or  constants. 


b.  Module 

AIOJNIT  uses  six  module  constants  for  AIO  board  addresses  and 
commands.  The  six  are: 

COMMANDJJPPER:  value  23h,  address  of  upper  AIO  command  port, 
COMMANDJ.OWER:  value  22h,  address  of  lower  AIO  command  port, 
DATAJJPPER:  value  21  h,  address  of  the  upper  AIO  data  port, 
DATAJ.OWER:  value  20h,  address  of  the  lower  AIO  data  port, 
INPUT_MODE:  value  47h,  AIO  command  to  receive  input,  and 
INTERRUPT_DISABLE:  value  07h,  AIO  command  to  disable  interrupts. 

AIO  INIT  uses  no  module  level  variables. 
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c.  Routine 


AlOJNIT  uses  the  variable  NULL  (type  Byte)  as  a  dummy  return 
variable  for  the  call  to  IOIN.  There  are  no  routine  level  constants. 


8.  Other  Routines  Called 

AlOJNIT  calls  four  external  assembly  language  routines,  DISABLEINT, 
ENABLEINT,  IOOUT,  and  IOIN,  to  accomplish  its  purpose.  These  four  routines 
are  declaired  externals.  Descriptions  of  these  routines  follow. 

a.  DISABLEINT 

AlOJNIT  uses  DISABLEINT  to  disable  the  Z-80  interupts  during  AIO 
board  initilization.  This  is  a  Zilog  recommended  practice  to  prevent  inadvertant 
interupts  during  the  initilization.  DISABLEINT  has  no  input  or  output  parameters; 
it  is  invoked  solely  by  name. 


b.  ENABLEINT 

ENABLEINT  is  the  last  routine  called  by  AlOJNIT.  It  enables  the  Z-80 
interupts  disable  by  the  earlier  call  to  DISABLEINT.  ENABLEINT  has  no  input  or 
output  parameters;  it  is  invoked  by  name  only. 


c.  IOOUT 

AlOJNIT  uses  IOOUT  to  write  commands  to  the  AIO  board.  IOOUT  is 
invoked  via: 

IOO UT(  IO_PORT,  VALUE  ) 

where  both  IOJPORT  and  VALUE  are  of  type  Byte.  IO_PORT  passes  the  address 
of  input/output  port  to  which  the  eight  bit  VALUE  will  be  written.  For  AlOJNIT 
both  IO_PORT  and  VALUE  are  passed  constants. 


d.  IOIN 

AlOJNIT  uses  JOIN  to  read  the  data  registers  of  the  AIO  board  and  clear 
them  of  any  value.  IOIN  is  invoked  by: 
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VALUE  :=  IOIN(  iO_PORT ) 

where  both  VALUE  and  IO_PORT  are  of  type  Byte.  IO_PORT  is  the  address  of 
the  input/output  port  from  which  data  is  read.  The  return  parameter  VALUE 
carries  the  eight  bit  value  read  in  from  the  port. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

AIOJNIT  has  no  output  parameters. 


b.  System  Configuration  Changes 

AIOJNIT  produces  several  changes  in  the  configuration  of  the  system. 
First,  during  the  program  execution,  the  system  interupts  are  disabled.  Second, 
the  AIO  board  is  put  into  polled  mode  and  the  AIO  board  is  ihnibited  from  issuing 
interrupts.  Last,  the  AIO  board  input  registers  are  cleared. 


10.  Routine  Testing 


a.  Description  of  Test 


No  tests  were  conducted  solely  on  AIOJNIT.  Rather,  it  was  tested  in 
conjunction  with  the  other  routines  which  could  not  function  at  all  if  AIOJNIT 
didn't  work. 


b.  Results  of  Test 

The  other  routines  worked,  therefore  AIOJNIT  works  properly. 


1 1 .  Reference  to  Listing 

The  program  listing  of  AIOJNIT  is  on  page  404. 


% 
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1 .  Routine  Name:  IN_CHAN_SEL 

2.  Part  of  AIO.PLZ.S  Module 

3.  Written  in  PL Z;  two  lines  of  executable  code. 


This  extremely  short  routine  writes  to  the  AIO  board  Channel  Select 
register  the  desired  channel  number.  This  forces  the  AIO  board  to  sample  the 
specified  input  channel  and  perform  an  analog  to  digital  conversion.  IN_CHAN_ 
SEL  uses  the  external  assembly  language  routine  IOOUT  to  write  the  value  to  the 
AIO  board. 


Calling  PLZ  Routines 


IN  CHAN  SEL 


,  Utility 

IOOUT  Module 


AIO  Board 


Selected  Analog 
Input  Channel 


Figure  78.  Relationship  of  IN_CHAN_SEL  to  Calling  PLZ  Routine 

and  IOOUT. 
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a.  Invocation  Statement 


IN_CHAN_SEL  is  invoked  by: 

IN_CHAN_SEL(  CHANNEL  ) 
where  CHANNEL  is  of  type  Byte. 


b.  Parameter  Passing  Schema 

The  input  parameter  CHANNEL  is  the  number  of  the  analog  to  digital 
channel  desired. 


c.  Routines  Which  Call 

IN_CHAN_SEL  can  be  called  by  any  PLZ  language  routine  using  the 
AIO  board.  The  AIO.PLZ.S  and  UTILITY  modules  must  be  linked  in  with  the  call¬ 
ing  routine.  For  this  thesis  effort,  IN_CHAN_SEL  was  used  during  initial  work 
with  the  AIO  board.  For  the  final  thesis  effort  routines,  an  pair  of  interrupt  driven 
assembly  language  routines,  TC_SAMPLE  and  TO_SAMPLE,  perform  the  chan¬ 
nel  selection,  initiation  of  analog  to  digital  conversion  function. 


7,.  Variables, -and  Constants 

a.  Global 

IN_CHAN_SEL  uses  no  globally  defined  constants  or  variables. 


b.  Module 

IN_CHAN_SEL  uses  the  module  level  constant  CHANNEL_SELECT, 
value  28  hexidecimal,  the  address  of  the  channel  selection  register  of  the  AIO 
board.  IN  CHAN  SEL  uses  no  module  level  variables. 


c.  Routine 

IN_CHAN  SEL  uses  no  routine  level  constants  and  variables. 
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IN_CHAN_SEL  calls  the  external  assembly  language  routine  IOOUT 
to  write  the  channel  number  to  the  AIO  board.  IOOUT  is  invoked  by: 

IOOUT(  IO_PORT,  VALUE ) 

where  both  IO_PORT  and  VALUE  are  of  type  Byte.  IO_PORT  is  the  address  of 
the  desired  10  port  and  VALUE  is  the  eight  bit  to  be  output. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

IN_CHAN_SEL  has  no  output  parameters. 

b.  System  Configuration  Changes 

IN_CHAN_SEL,  by  selecting  a  channel,  initiates  an  analog  to  digital 
conversion  on  the  selected  channel  of  the  AIO  board. 


IQ.  Routine  Testing 

a.  Description  of  Test 

IN_CHAN_SEL  was  tested  in  conjuction  with  other  routines  using  the 
AIO  board.  If  IN_CHAN_SEL  didn’t  work,  routine  IN_DIGITALP  would  not  find  the 
correct  value  (from  a  known,  constant  input  voltage)  in  the  AIO  data  registers. 
Several  channels  were  selected  by  IN_CHAN_SEL  and  read  by  IN_DIGITALP. 


b.  Results  of  Test 

The  digital  values  corresponding  to  the  analog  inputs  were  found  by 
IN_DIGITALP  in  the  AIO  data  registers. 


1 1 .  Reference  to  Listing 

The  listing  of  IN_CHAN_SEL  can  be  found  on  page  404. 
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1 .  Routine  Name:  IN_DIGITALP 

2.  Part  of  AIO.PLZ.S  Module 

3.  Written  in  PLZ;  four  lines  of  executable  code. 


IN_DIGITALP  reads  the  data  registers  of  the  AIO  board  to  obtain  the 
digital  value  converted  from  the  analog  channel  selected  by  routine  IN_CHAN_ 
SEL.  IN_DIGITALP  loops,  polling  the  AIO  status  register  until  an  analog  to  digital 
conversion  is  complete.  Then  IN_DIGITALP  reads  data  from  both  AIO  eight  bit 
data  registers  and  combines  them  into  a  single  sixteen  bit  Integer  value.  Note 
that  AIO  analog  to  digital  conversion  yields  only  12  bits  of  information.  Thus  the 
upper  data  register  holds  only  four  bits  of  information. 


Calling  PLZ  Routines 

\  / 

IN  DIGITALP 


Status 


Data 


AIO  Board 


Selected  Analog 
Input  Channel 


Figure  79.  Relationship  of  IN_DIGITALP  to  Calling  PLZ  Routine 

and  IOIN. 
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a.  Invocation  Statement 


IN_D1GITALP  is  invoked  from  a  calling  PL Z  routine  by: 

VALUE  :=  IN_DIGITALP 

where  the  return  parameter  VALUE  is  of  type  Integer, 

b.  Parameter  Passing  Schema 

IN_DIGITALP  has  no  input  parameters.  The  input  channel  is  selected 
in  advance  by  IN_CHAN_SEL. 


c.  Routines  Which  Call 

Any  PLZ  routine  needing  to  obtain  analog  to  digital  conversions  from 
the  AIO  board  can  use  IN_DIGITALP.  The  AIO.PLZ.S  and  UTILITY  modules  must 
be  linked  in  with  the  calling  routine's  module.  IN_DIGITALP  is  not  present  in  the 
final  routines  for  this  thesis  effort.  IN_DIGITALP  was  used  during  initial  work  to 
learn  how  to  use  the  AIO  board. .  In  the  final  theis  effort  routines,  an  interrupt- 
paced  assembly  language  routine,  COLLECTER,  is  used  read  data  in  from  the 
AIO  board. 


7.  Variables  and  Constants 

a.  Global 

IN_DIGITALP  uses  no  globally  defined  variables  or  constants. 

b.  Module 

Four  module  level  constants  are  used  by  IN_DIGITALP.  Their  values 
and  uses  are 
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STATUS: 


Value  29  hex,  the  address  of  the  AIO  board  status  register 


MASK:  Value  01  hex,  a  logical  masking  word  to  retain  only  the 

least  significant  bit 


DATAJJPPER:  Value  21  hex,  the  address  of  the  upper  AIO  board  data 
register 

DATA_LOWER:  Value  20  hex,  the  address  of  the  lower  AIO  board  data 
register 


IN  DIGITALP  uses  no  module  level  variables. 


c.  Routine 

IN_DIGITALP  uses  no  routine  level  variables  or  constants.  The  expli¬ 
cit  constant  100  hex  (represented  by  %100)  is  employed  in  the  combining  of  the 
upper  and  lower  data  values  from  the  AIO  board. 


8.  Other  Routines  Called 

The  external  assembly  language  routine  IOIN  is  used  by  IN_DIGITALP 
to  both  check  the  AIO  board  status  register  and  to  read  in  the  converted  values. 
IOIN  is  invoked  with: 

VALUE  :«  IOIN(  IO_PORT ) 

where  both  VALUE  and  IO_PORT  are  of  type  Byte.  The  input  parameter  IO_ 
PORT  is  the  address  (00  hex  to  FF  hex)  of  the  input/output  port  from  which  the 
output  parameter  VALUE  is  to  be  obtained. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

IN_DIGITALP  returns  to  its  calling  routine  a  single,  type  Integer,  return 
para-  meter  called  VALUE.  It  holds  the  twelve  bit  value  formed  from  the  upper 
(four  bits)  and  lower  (eight  bits)  read  from  the  AIO  board’s  two  data  registers. 
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b.  System  Configuration  Changes 

The  configuration  of  the  system  is  not  changed  by  IN_DIGITALP  aside 
from  clearing  the  AIO  board  data  registers. 

10.  Routine  Testing 

a.  Description  of  Test 

IN_DIGITALP  was  tested  by  having  it  read  from  an  AIO  channel  that 
was  fed  constant  voltages. 

b.  Results  of  Test 

IN_DIGITALP  provided  correct  digital  values  to  the  calling  routine. 

11.  Reference  to  Listing 

The  program  listing  for  IN_DIGITALP  is  on  page  405. 
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1.  Routine  Name:  IN_DIGITALT 

2.  Part  of  AIO.PL2.S  Module 

3.  Written  in  PLZ;  three  lines  of  executable  code. 


IN_DIGITALT  is  a  combination  of  IN_CHAN_SEL  and  IN_DIGITALP 
and  con-  sists  simply  of  calls  to  those  two  routines.  Its  purpose  is  to  select  an  AIO 
channel  for  input,  then  wait  for  the  analog  to  digital  conversion  to  occur,  and 
finally  read  in  the  con-  verted  value.  IN_DIGITALT  was  written  for  those  PLZ 
programs  that: 

a.  can  afford  to  wait,  or 

b.  do  not  need  to  accomplish  other  tasks  during  the  analog  to 
digital  conversion  period. 


Calling  PLZ  Routines 


Figure  80.  Relationship  of  IN_DIGITALT  to  Calling  PLZ  Routine, 
IN  CHAN  SEL  and  IN  DIGITALP. 
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a.  Invocation  Statement 


IN_DIGITALT  is  invoked  by: 

VALUE  :=  IN_DIGITALT(  CHANNEL ) 
where  both  VALUE  and  CHANNEL  are  of  type  Byte. 


b.  Parameter  Passing  Schema 

The  single  input  parameter  for  IN_DIGITALT,  CHANNEL,  is  the  same 
as  for  routine  IN_DIGITALP,  the  number  of  the  AIO  input  channel  on  which  the 
analog  to  digital  conversion  will  be  made.  CHANNEL  has  a  defined  range  of  0  to 
F  hexidecimal. 


c.  Routines  Which  Call 

Any  PLZ  routine  needing  to  get  analog-to-digital  values  from  the  AIO 
board  can  use  IN_DIGITALT.  To  call  IN_DIGITALT,  both  the  AIO.PLZ.S  and 
UTILITY  modules  must  be  linked  in  with  the  calling  routine.  As  with  the  other 
routines  of  the  AIO.PLZ.S  Module,  IN_DIGITALT  was  used  during  initial  work  with 
the  AIO  board.  IN_DIGITALT  does  not  appear  in  any  of  the  final  programs  of  this 
thesis  effort. 


7,  variables  and  Constants 

IN  DIGITALT  uses  no  variables  or  constants. 


8.  Other  Routines  Called 

IN_DIGITALT  calls  IN_CHAN_SEL  to  select  the  analog  input  channel 
on  the  AIO  board  and  IN_DIGITALP  to  read  in  the  converted  digital  value  from 
theAlO  board. 

a.  IN_CHAN_SEL  initiates  an  analog  to  digital  conversion  on  a  specific 
analog  input  channel.  It  is  invoked  via: 

IN_CHAN_SEL(  CHANNEL  ) 
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where  the  input  parameter  CHANNEL,  type  Byte,  specifies  the  desired  analog 
channel.  CHANNEL  is  the  input  parameter  for  INJOIGITALT. 

b.  IN_DIGITALP  reads  the  converted  digital  values  from  the  AIO  data  regis¬ 
ters  and  combines  them  to  form  a  single  integer  type  value.  IN_DIGITALP  is 
invoked  by: 


VALUE  :=  IN_DIGITALP 

where  the  return  parameter  VALUE,  type  Integer,  holds  the  converted,  single 
value.  VALUE  is  then  the  output  parameter  for  IN_DIGITALT. 


9.  Output  of  Routine 

a.  Parameter  Passing  Schema 

IN_DIGITALT  has  a  single  output  parameter,  VALUE.  This  sixteen  bit 
parameter  passes  the  twelve  bits  of  information  read  from  the  AIO  board  data 
registers  back  to  the  calling  PLZ  routine. 


b.  System  Configuration  Changes 

IN_DIGITALT  initiates  an  analog  to  digital  conversion  on  a  specified 
AIO  input  channel.  Later,  IN_DIGITALT  clears  the  data  registers  of  the  AIO  board 
when  it  reads  the  converted  analog  values. 


IQ.  Routine  Testing 

IN_DIGITALT  was  not  tested  as  it  is  simply  the  combination  of  IN_ 
CHAN_SEL  and  IN_DIGITALP.  Both  of  these  routines  were  tested  and  found  to 
function  correctly.  Testing  was  considered  unnecessary. 


11.  Reference  to  Listing 

The  program  listing  of  IN_DIGITALT  is  on  page  405. 
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1.  Routine  Name:  OUT_ANALOG 

2.  Part  of  AIO.PLZ.S  Module 


3.  Written  in  PL Z;  nine  lines  of  executable  code. 


4.  Synopsis  of  Routine 

OUT_ANALOG  takes  the  integer  value  passed  to  it,  splits  the  value 
into  two  bytes,  and  outputs  the  digital  values  to  the  AIO  board  for  conversion  to  an 
analog  signal.  OUT_ANALOG  can  output  on  either  of  the  two  digital  to  analog 
channels  of  the  AIO  board.  The  writing  of  the  bytes  is  accomplished  with  the 
external  routine  IOOUT. 


5.  Routine  Relationships  Diagram 


Figure  81 .  Relationship  of  OUT_ANALOG  to  Calling  PLZ  Routine 

and  IOOUT. 
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a.  Invocation  Statement 


OUT_ANALOG  is  called  from  a  PLZ  routine  with: 
OUT_ANALOG(  CHANNEL,  VALUE  ) 
where  CHANNEL  is  type  Byte  and  VALUE  is  type  Integer. 


b.  Parameter  Passing  Schema 

The  two  input  parameters  CHANNEL  and  VALUE  pass  to  OUT_ 
ANALOG  the  digital-to-analog  channel  desired  for  output  and  the  twelve  bits  of 
digital  information  to  be  converted  to  an  analog  signal  by  the  AIO  board.  OUT_ 
ANALOG  assumes  that  VALUE  has  only  twelve  significant  bits;  as  an  Integer  it  is 
a  sixteen  bit  value. 


c.  Routines  Which  Call 

OUT_ANALOG  can  be  used  by  any  PLZ  routine  which  needs  to  output 
analog  values.  The  AIO.PLZ.S  and  UTILITY  modules  need  to  linked  in  with  the 
calling  routine.  OUT_ANALOG  is  not  used  by  any  routines  of  this  thesis  effort. 
Like  the  other  PLZ  language  routines  of  the  AIO.PLZ.S  Module  it  was  used  for 
initial  investigations  of  the  AIO  board.  An  assembly  language  version  of  OUT_ 
ANALOG,  routine  OUTDA,  was  written  but  is  not  a  part  of  the  final  thesis  effort 
routines. 


a.  Global 

OUT_ANALOG  uses  no  globally  defined  variables  or  constatnts. 


b.  Module 

OUT_ANALOG  uses  four  module  level  constants.  Their  definitions 
and  values  are  on  the  next  page. 
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DA_CHANNEL_1_UPPER:  Value  2D  hex,  10  port  address  of  AIO  digital  to 

analog  channel  one,  upper  four  bit  register. 

DA_CHANNEL_1_L0WER:  Value  2C  hex,  10  port  address  of  AIO  digital  to 

analog  channel  one,  lower  eight  bit  register. 


DA_CHANNEL_2_UPPER:  Value  2F  hex,  10  port  address  of  AIO  digital  to 

analog  channel  two,  upper  four  bit  register. 


D A_CH AN N E L_2_L0WE R :  Value  2E  hex,  10  port  address  of  AIO  digital  to 

analog  channel  two,  lower  eight  bit  register. 

These  constants  are  used  by  OUT_ANALOG  when  calling  IOOUT.  OUT_ 
ANALOG  uses  no  module  level  variables. 


c.  Routine 

A  single  routine  level  constant,  OUTVALUE,  of  type  Byte  is  used  by 
OUT_  ANALOG.  It  is  set  to  the  lower  eight  bits  of  the  input  integer  VALUE  and  is 
then  used  to  output  to  the  lower  data  register  of  the  AIO  output  channel.  OUT¬ 
VALUE  is  next  set  to  the  upper  four  bits  of  the  twelve  bit  input  value.  OUTVALUE 
is  then  used  written  to  the  upper  data  register  of  the  AIO  output  channel.  OUT- 
ANALOG  uses  no  routine  level  constants. 


9,  .Other  Routines  Called 

OUT_ANALOG  uses  two  PLZ  type  conversion  functions  and  one  ex¬ 
ternal  routine,  IOOUT.  The  type  conversions,  integer  to  byte  and  byte  to  integer, 
are  used  in  the  splitting  of  the  input  parameter  VALUE  in  to  the  upper  four  bit  and 
lower  eight  bit  byte  values  passed  to  the  AIO  board  via  IOOUT.  IOOUT  is  an  ex¬ 
ternal  assembly  language  routine  of  the  Utility  Module.  It  permits  PLZ  language 
routines  direct  access  to  input  output  ports.  IOOUT  is  invoked  via: 

IOOUT(  IO_PORT,  VALUE ) 

where  both  IO_PORT  and  VALUE  are  of  type  Byte.  IO_PORT  is  the  number  or 
address  the  input/output  port  that  VALUE  is  to  be  written  to.  IOOUT  has  no  return 
parameters. 
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[•MS] 


a.  Parameter  Passing  Schema 

OUT_ANALOG  has  no  output  parameters. 


b.  System  Configuration  Changes 

OUT_ANALOG  sets  one  of  the  digital  to  analog  channels  to  a  value. 
That  value  will  continue  to  be  output  by  the  analog  channel  until  either  another 
value  is  written  to  it  or  the  AIO  board  is  turned  off. 


a.  Description  of  Test 

OUT_ANALOG  was  tested  through  a  looping  routine  which  read  in  an 
analog  to  digital  conversion  value,  via  IN_DIGITALT,  and  then  output  that  value 
back  through  OUT_ANALOG.  A  low  frequency  sine  wave  input  was  applied  to 
the  analog  input.  Both  the  sine  input  and  the  output  of  the  digital  to  analog 
channel  were  monitored  by  an  osci IHscope. 


b.  Results  of  Test 

The  output  channel  tracked  the  input  channel  with  the  time  delay 
produced  by  the  processing  delay. 


The  listing  of  OUT_ANALOG  is  on  page  406. 
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Program  Listings  of  AIO.PLZ.S  Module 

The  following  pages  are  a  listing  of  the  AIO.PLZ.S  Module  routines 
This  is  not  a  compiled  or  assembled  listing;  it  is  PLZ  source  code. 

Page  Number  _ Contents _ 

412  Introduction,  Constant  Definitions,  and  External 

Definitions 


41 3  AIOJNIT  and  IN_CHAN_SEL  Procedures 

414  INDIGITALP  and  INDIGITALT  Procedure 

415  OUT_ANALOG  Procedure 
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END  OUT_ANALOG 


Appendix  H:  Scale  Factor  Module 


Scale_Factor  Module  is  a  compiled  set  of  PLZ  language  routines 
which  implement  the  Set  Up  Scale  Factor  File  process  shown  in  Figure  3  in  the 
introduction.  With  the  routines  within  Scale  Factor,  a  user  can  create  or  modify  a 
disk  file  of  scale  factors.  Due  to  the  difficulties  encountered  in  debugging  the 
Collect  and  Store  Data  process  routines,  Scale_Factor  Module  was  not  integra¬ 
ted  in  with  the  other  software  of  this  thesis  effort. 


The  routines  of  Scale_Factor  Module  are  listed  here  to  show  how  the 
10  improvements  of  the  Enhancements  Module  can  be  used.  The  module  is 
organized  into  an  executive  /  subordinate  routine  structure  as  shown  by  Figure 
82  below.  The  module  executes  the  subordinate  routines  in  sequence.  The  most 
complex  of  the  subordinate  routines,  CHANGE_SCALE,  makes  extensive  use  of 
the  Enhanacements  Module  routines.  The  program  flow  within  CHANGE_ 
SCALE  is  shown  in  Figure  83.  Both  figures  are  present  to  aid  reader  understand¬ 
ing  of  the  execution  of  Scaie_Factor  Module. 


The  listings  of  Sca!e_Factor  Module  routines  are  on  the  following  pages. 


41 9  Constant,  Type,  External,  and  Global  Variable 

Definitions. 

419- 420  INITIALIZE  Procedure 

420  WRITELN  Procedure 

420  READLN  Procedure 

420- 421  WRITE  Procedure 

421  READ_CH  Procedure 

421  WRITE_CH  Procedure 

421  ACCEPTABLE  Procedure 

422  GETJDENTIFIER  Procedure 

422- 423  FORM_FILE_NAME  Procedure 

423  CREATE_SCALE_FILE  Procedure 

423- 424  OPEN  SCALE  FILE  Procedure 


Appendix  H 


416 


Appendix  H 


417 


Figure  83.  Program  Execution  Flow  Within  CHANGE_SCALE 
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